FX::QThreadPool Class Reference

#include <QThread.h>

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

enum FX::QThreadPool::CancelledState

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:

QThread.h