Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members

FX::FXThreadPool Class Reference

A Thread Pool manages execution of tasks on a number of worker-threads. More...

#include <FXThreadPool.h>

Inheritance diagram for FX::FXThreadPool:
FX::FXRunnable

List of all members.

Public Member Functions

 FXThreadPool (FXuint sz=256)
 Construct an empty thread pool, with given task-queue size.
FXbool active () const
 Return true if running.
FXbool setSize (FXuint sz)
 Change task queue size, return true if success.
FXuint getSize () const
 Return task queue size.
FXuint getRunningTasks () const
 Return number of tasks.
FXuint getRunningThreads () const
 Return number of threads.
FXbool setMinimumThreads (FXuint n)
 Change minimum number of worker threads; default is 1.
FXuint getMinimumThreads () const
 Return minimum number of worker threads.
FXbool setMaximumThreads (FXuint n)
 Change maximum number of worker threads; default is #processors.
FXuint getMaximumThreads () const
 Return maximum number of worker threads.
FXbool setExpiration (FXTime ns=forever)
 Change expiration time for excess workers to terminate.
FXTime getExpiration () const
 Get expiration time.
FXbool setStackSize (FXuval sz)
 Change stack size (0 for default stack size)
FXuval getStackSize () const
 Get stack size.
FXuint start (FXuint count=0)
 Start the thread pool with an initial number of threads equal to count.
FXbool execute (FXRunnable *task, FXTime blocking=forever)
 Execute a task on the thread pool by entering it into the queue.
FXbool executeAndWait (FXRunnable *task, FXTime blocking=forever)
 Execute task on the thread pool by entering int into the queue.
FXbool executeAndWaitFor (FXRunnable *task, FXCompletion &comp, FXTime blocking=forever)
 Execute task on the thread pool by entering int into the queue.
FXbool wait ()
 Wait until task queue becomes empty and all tasks are finished, and process tasks to help the worker threads in the meantime.
FXbool waitFor (FXCompletion &comp)
 Wait until completion becomes signaled, and process tasks to help the worker threads in the meantime.
FXbool stop ()
 Stop thread pool, and block posting of any new tasks to the queue.
virtual ~FXThreadPool ()
 Stop the thread pool and then delete it.
- Public Member Functions inherited from FX::FXRunnable
 FXRunnable ()
 Construct a runnable.
virtual ~FXRunnable ()
 Destroy a runnable.

Static Public Member Functions

static FXThreadPoolinstance ()
 Return calling thread's thread pool.
static void instance (FXThreadPool *pool)
 Change calling thread's thread pool.

Detailed Description

A Thread Pool manages execution of tasks on a number of worker-threads.

A task executed by the thread pool is queued up until a worker-thread becomes available to run it. To accomodate fluctuations in workloads and minimize resources, the number of worker- threads can be allowed to vary between a minimum and a maximum number. Idle worker-threads which receive no assignments within a specified amount of time will automatically terminate, thereby reduce system-resources used by the program. By default, the minimum number of worker-threads is 1, and the maximum number of worker- threads is equal to the number of processors in the system. During peak workloads, when the task queue may start to fill up, and no new worker- threads can be created, the calling thread to block until there is room in the queue for more tasks. However, if a non-default value is passed for the blocking-parameter to execute(), the calling thread will be blocked for only a finite amount of time (non-zero blocking value) or return immediately (zero blocking value). Failure to queue up a new task will result in execute() returning a false. The tasks which are passed to the thread pool are derived from FXRunnable. In order to perform some useful function, subclasses of FXRunnable should overload the run() function. Uncaught exceptions thrown by a task are intercepted by the thread pool and rethrown after the necessary cleanup, and cause the worker thread to end prematurely. When the thread pool is stopped, it will wait until all tasks are finished, and then cause all worker-threads to terminate. The thread pool becomes associated (through a thread-local variable) with the calling thread when start() is called; this association lasts until stop() is called. In addition, each worker will similarly be associated with the thread pool. Thus both the main thread as well as the worker threads can easily find the thread pool through the member-function instance().


Member Function Documentation

FXbool FX::FXThreadPool::execute ( FXRunnable task,
FXTime  blocking = forever 
)

Execute a task on the thread pool by entering it into the queue.

If a spot becomes available in the task queue within the timeout interval, add the task to the queue and return true. Return false if the task could not be added within the given time interval. Possibly starts additional worker threads if the maximum number of worker threads has not yet been exceeded.

FXbool FX::FXThreadPool::executeAndWait ( FXRunnable task,
FXTime  blocking = forever 
)

Execute task on the thread pool by entering int into the queue.

If the task was successfully added, the calling thread will temporarily enter the task-processing loop, and help out the worker-threads until all tasks have finished processing. Return false if the task could not be added within the given time interval. Possibly starts additional worker threads if the maximum number of worker threads has not yet been exceeded.

FXbool FX::FXThreadPool::executeAndWaitFor ( FXRunnable task,
FXCompletion comp,
FXTime  blocking = forever 
)

Execute task on the thread pool by entering int into the queue.

If the task was successfully added, the calling thread will temporarily enter the task-processing loop, and help out the worker-threads until the completion becomes signaled. Return false if the task could not be added within the given time interval. Possibly starts additional worker threads if the maximum number of worker threads has not yet been exceeded.

FXuint FX::FXThreadPool::start ( FXuint  count = 0)

Start the thread pool with an initial number of threads equal to count.

Returns the number of threads actually started. An association will be established between the calling thread and the thread pool. This association lasts until stop() is called. If another threadpool was already started before by the calling thread, no new association will be established.

FXbool FX::FXThreadPool::stop ( )

Stop thread pool, and block posting of any new tasks to the queue.

Enter the task-processing loop and help the worker-threads until the task queue is empty, and all tasks have finished executing. The association between the calling thread, established when start() was called, will hereby be dissolved, if the calling thread was associated with this thread pool. Return false if the thread pool wasn't running.

FXbool FX::FXThreadPool::wait ( )

Wait until task queue becomes empty and all tasks are finished, and process tasks to help the worker threads in the meantime.

If the thread pool was not running, return immediately with false; otherwise, return when the queue is empty and all tasks have finished.

FXbool FX::FXThreadPool::waitFor ( FXCompletion comp)

Wait until completion becomes signaled, and process tasks to help the worker threads in the meantime.

If the thread pool was not running, return immediately with false; otherwise, return when the completion becomes signaled, or when the thread pool is stopped. Immediately return with false if the thread pool wasn't running.


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

Copyright © 1997-2016 Jeroen van der Zijp