CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | List of all members
cugl::ThreadPool Class Reference

#include <CUThreadPool.h>

Public Member Functions

 ThreadPool ()
 
 ~ThreadPool ()
 
void dispose ()
 
virtual bool init (int threads=4)
 
void addTask (const std::function< void()> &task)
 
void stop ()
 
bool isStopped () const
 
bool isShutdown () const
 

Static Public Member Functions

static std::shared_ptr< ThreadPoolalloc (int threads=4)
 

Detailed Description

Class to providing a collection of worker threads.

This is a general purpose class for performing tasks asynchronously. There is no notification process for when a task is complete. Instead, your task should either set a flag, or execute a callback when it is done.

There are some important safety considerations for using this class over direct thread objects. For example, stopping a thread pool does not shut it down immediately; it just marks it for shutdown. Because of mutex locks, it is not safe to delete a thread pool until it is completely shutdown.

More importantly, we do not allow for detached threads. This makes no sense in this application, because the threads share a resource (_taskQueue) with the main thread that will be deleted. It is therefore unsafe for the threads to ever detach.

See the class AssetManager for an example of how to use a thread pool.

Constructor & Destructor Documentation

◆ ThreadPool()

cugl::ThreadPool::ThreadPool ( )
inline

Creates a thread pool with no active threads.

You must initialize this thread pool before use.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a thread pool on the heap, use one of the static constructors instead.

◆ ~ThreadPool()

cugl::ThreadPool::~ThreadPool ( )
inline

Deletes this thread pool, destroying all resources.

It is a bad idea to destroy the thread pool if the pool is not yet shut down. The task queue is shared by the child threads, so we cannot delete it until all the threads complete. This destructor will block unti showndown.

Member Function Documentation

◆ addTask()

void cugl::ThreadPool::addTask ( const std::function< void()> &  task)

Adds a task to the thread pool.

A task is a void returning function with no parameters. If you need state in the task, you should use a method call for the state. The task will not be executed immediately, but must wait for the first available worker.

Parameters
taskthe task function to add to the thread pool

◆ alloc()

static std::shared_ptr<ThreadPool> cugl::ThreadPool::alloc ( int  threads = 4)
inlinestatic

Returns a newly allocated thread pool with the given number of threads.

You can specify the number of simultaneous worker threads. We find that 4 is generally a good number, even if you have a lot of tasks. Much more than the number of cores on a machine is counter-productive.

Parameters
threadsthe number of threads in this pool
Returns
a newly allocated thread pool with the given number of threads.

◆ dispose()

void cugl::ThreadPool::dispose ( )

Disposes this thread pool, releasing all memory.

A disposed thread pool can be safely reinitialized. However, it is a bad idea to destroy the thread pool if the pool is not yet shut down. The task queue is shared by the child threads, so we cannot delete it until all the threads complete. This destructor will block unti showndown.

◆ init()

virtual bool cugl::ThreadPool::init ( int  threads = 4)
virtual

Initializes a thread pool with the given number of threads.

You can specify the number of simultaneous worker threads. We find that 4 is generally a good number, even if you have a lot of tasks. Much more than the number of cores on a machine is counter-productive.

Parameters
threadsthe number of threads in this pool
Returns
true if the threed pool is initialized properly, false otherwise.

◆ isShutdown()

bool cugl::ThreadPool::isShutdown ( ) const
inline

Returns whether the thread pool has been shut down.

A shut down thread pool has no active threads and is safe for deletion.

Returns
whether the thread pool has been shut down.

◆ isStopped()

bool cugl::ThreadPool::isStopped ( ) const
inline

Returns whether the thread pool has been stopped.

A stopped thread pool is marked for shutdown, but it shutdown has not necessarily completed. Shutdown will be complete when the current child threads have finished with their tasks.

Returns
whether the thread pool has been stopped.

◆ stop()

void cugl::ThreadPool::stop ( )

Stop the thread pool, marking it for shut down.

A stopped thread pool is marked for shutdown, but it shutdown has not necessarily completed. Shutdown will be complete when the current child threads have finished with their tasks.


The documentation for this class was generated from the following file: