#include <QThread.h>
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.
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) |
typedef void* FX::QThreadPool::handle |
A handle to a job within the thread pool.
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.
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.