FX::QThreadPool Class Reference

#include <QThread.h>

List of all members.


Detailed Description

Provides a pool of worker threads.

Thread pools are an old & common invention used to work around the cost of creating and destroying a thread. They permit you to gain all the advantages of multi-threaded programming to a fine-grained level without many of the costs. Thus, they are ideal for when you regularly have small tasks to be carried out in parallel with the main execution.

Typically to send a job to a thread pool costs barely more than waking a sleeping thread. If there are no threads available (ie; they're all processing a job), the job enters a FIFO queue which is emptied as fast as the worker threads get through them. You furthermore can delay the execution of a job for an arbitrary number of milliseconds - thus a timed call dispatcher comes for free with this class.

Jobs can be waited upon for completion & cancelled. FX::FXProcess provides a process-wide thread pool which is created upon first-use - certain functionality such as the filing system monitor (FX::FXFSMonitor) use the process thread pool to run checks as well as dispatch notifications of changes.

Usage:

FXProcess::threadPool().dispatch(Generic::BindFuncN(obj, method, pars));

Cancelling jobs with cancel() can get tricky. If it's a simple case of cancelling it before it has run, all is good and Cancelled is returned. If the job is already running, you can optionally have cancel() wait until it's returned but in either case WasRunning is returned (if the job completed, the functor is deleted as usual). Be aware that if your job reschedules itself, cancel() when returning WasRunning won't actually have cancelled the job and you'll need to call it again. Suggested code is as follows:

while(QThreadPool::WasRunning==threadpool.cancel(job));

Public Types

enum  CancelledState { NotFound, Cancelled, WasRunning }
typedef void * handle

Public Member Functions

 QThreadPool (FXuint total=FXProcess::noOfProcessors(), bool dynamic=false)
FXuint total () const throw ()
FXuint maximum () const throw ()
FXuint free () const throw ()
void setTotal (FXuint newno)
bool dynamic () const throw ()
void setDynamic (bool v)
handle dispatch (FXAutoPtr< Generic::BoundFunctorV > code, FXuint delay=0)
CancelledState cancel (handle code, bool wait=true)
bool reset (handle code, FXuint delay)
bool wait (handle code, FXuint period=FXINFINITE)

Member Typedef Documentation

typedef void* FX::QThreadPool::handle

A handle to a job within the thread pool.


Member Enumeration Documentation

Cancelled state.

Enumerator:
NotFound  Job not found.
Cancelled  Job cancelled before it could run.
WasRunning  Job was already running.


Constructor & Destructor Documentation

FX::QThreadPool::QThreadPool ( FXuint  total = FXProcess::noOfProcessors(),
bool  dynamic = false 
)

Constructs a thread pool containing total threads, the default being the number of processors in the local machine. dynamic when true means create threads on demand up until total.


Member Function Documentation

FXuint FX::QThreadPool::total (  )  const throw ()

Returns the number of threads in total in the pool.

FXuint FX::QThreadPool::maximum (  )  const throw ()

Returns the maximum number of threads permitted.

FXuint FX::QThreadPool::free (  )  const throw ()

Returns the number of free threads in the pool.

void FX::QThreadPool::setTotal ( FXuint  newno  ) 

Sets the number of threads in the pool, starting new ones if necessary or retiring free ones. If the pool is dynamic, merely sets the maximum permitted.

bool FX::QThreadPool::dynamic (  )  const throw ()

Returns if the pool is dynamic.

void FX::QThreadPool::setDynamic ( bool  v  ) 

Sets if the pool is dynamic.

handle FX::QThreadPool::dispatch ( FXAutoPtr< Generic::BoundFunctorV code,
FXuint  delay = 0 
)

Dispatches a worker thread to execute this job, delaying by delay milliseconds

CancelledState FX::QThreadPool::cancel ( handle  code,
bool  wait = true 
)

Cancels a previously dispatched job. If the job is currently being executed and wait is true, waits for that job to complete before returning.

bool FX::QThreadPool::reset ( handle  code,
FXuint  delay 
)

Resets a timed job to a new delay. If the job is currently executing or has finished, returns false.

bool FX::QThreadPool::wait ( handle  code,
FXuint  period = FXINFINITE 
)

Waits for a job to complete.


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

(C) 2002-2008 Niall Douglas. Some parts (C) to assorted authors.
Generated on Fri Jun 13 22:29:00 2008 for TnFOX by doxygen v1.5.6