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< ThreadPool >	alloc (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

task	the 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

threads

the 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

threads

the 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:

• cugl/include/cugl/util/CUThreadPool.h