Qore::Thread::ThreadPool Class Reference

This class defines a thread pool that grows and shrinks dynamically within user-defined limits according to the task load placed on it. More...

#include <QC_ThreadPool.dox.h>

Public Member Methods
	constructor (int max=0, int minidle=0, int maxidle=0, timeout release_ms=5s)
	creates the pool with the given parameters; idle worker threads are started immediately if necessary More...
	destructor ()
	destroys the pool; any worker threads are detached and pending tasks not yet executed are canceled; to wait for all worker threads to complete, call ThreadPool::stopWait() first More...
	stop ()
	stops the thread pool and returns immediately; queued tasks are canceled More...
	stopWait ()
	stops the thread pool and does not return until all submitted tasks have been executed and all worker threads have been stopped More...
	submit (code task, *code cancel)
	submit a task to the pool More...
string	toString ()
	returns a description of the ThreadPool More...

Detailed Description

This class defines a thread pool that grows and shrinks dynamically within user-defined limits according to the task load placed on it.

The ThreadPool can also pre-allocate idle threads for quickly allocating threads to tasks submitted through ThreadPool::submit() for cases when very low latency is required (for example, for allocating already waiting threads to incoming Socket connections).

A worker thread is started while the ThreadPool is running that waits for tasks in an internal task queue and allocates the tasks to worker threads. If an idle thread is available, the task is submitted to that thread immediately, otherwise, if the ThreadPool is not already at maximum capacity (the max argument to ThreadPool::constructor()), a new thread is started and the task is allocated to the new thread. Otherwise, the task will block until a thread becomes free, at which time the task is allocated to the newly-freed worker thread.

When a worker thread has no more tasks to execute, it will either be returned to the pool to wait in an idle state if possible, or it will terminate. Threads are returned to the idle pool if there are fewer than maxidle threads in the idle pool already or if there are more tasks in the queue than idle threads.

ThreadPools downscale over time when demand is lower according to the release_ms argument to ThreadPool::constructor(); when there more than minidle threads in the idle pool, then for each time period defined by release_ms, a single thread in the idle pool is released until the number of threads in the idle pool reaches minidle.

Therefore the minidle argument defines the "ground state" of the ThreadPool (how many idle threads are waiting for tasks), and the release_ms argument defines the period in which the ThreadPool returns to its ground state after demand for threads results in a condition where there are temporarily more than minidle threads in the idle pool.

If the ThreadPool is stopped when tasks are still in the queue, then any cancellation closure or call reference for the task is executed; see ThreadPool::submit() for more information.

Restrictions:

Qore::PO_NO_THREAD_CLASSES

Example:

ThreadPool tp(10, 2, 4);

Since

Qore 0.8.8

Member Function Documentation

constructor()

Qore::Thread::ThreadPool::constructor	(	int	max = 0,
		int	minidle = 0,
		int	maxidle = 0,
		timeout	release_ms = 5s
	)

creates the pool with the given parameters; idle worker threads are started immediately if necessary

Example:

ThreadPool tp(10, 2, 4);

When worker threads complete, the thread is returned to the pool if there are less than minidle threads in the idle list or there are more tasks in the queue than the number of idle threads.

Parameters

max	the maximum number of threads in the pool
minidle	the minimum number of free idle threads to keep ready
maxidle	the maximum number of idle threads to keep ready
release_ms	this value gives the delay in terminating single idle threads when maxidle > minidle and there are more than minidle threads in the idle pool; for example, if release_ms = 10s then when there are more than minidle threads in the idle pool, every 10 seconds an idle thread is terminated until there are minidle threads in the pool. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 2m = two minutes, etc.)

Exceptions

THREADPOOL-ERROR

minidle > max, maxidle > max or minidle > maxidle, or release_ms < 0

destructor()

Qore::Thread::ThreadPool::destructor

(

)

destroys the pool; any worker threads are detached and pending tasks not yet executed are canceled; to wait for all worker threads to complete, call ThreadPool::stopWait() first

Example:

delete tp;

stop()

Qore::Thread::ThreadPool::stop

(

)

stops the thread pool and returns immediately; queued tasks are canceled

Example:

tp.stop();

This method detaches all worker threads immediately, stops the ThreadPool, and returns immediately; after this method has been executed once no more tasks can be submitted to the ThreadPool.

Queued tasks not yet processed by a worker thread are canceled.

Note

if any worker threads are still running; they are detached from the ThreadPool and terminate independently from the ThreadPool

See also

ThreadPool::stopWait()

stopWait()

Qore::Thread::ThreadPool::stopWait

(

)

stops the thread pool and does not return until all submitted tasks have been executed and all worker threads have been stopped

Example:

tp.stopWait();

This method does not return until the ThreadPool has been stopped and all worker threads have also been stopped. After this method has been executed once no more tasks can be submitted to the ThreadPool.

See also

ThreadPool::stop()

submit()

Qore::Thread::ThreadPool::submit	(	code	task,
		*code	cancel
	)

submit a task to the pool

Example:

tp.submit(sub () { call_function(arg); });

Parameters

task	the closure or call reference to execute
cancel	an optional closure or call reference to execute if the ThreadPool is stopped before the task can be executed; note that cancellation code is run serially for each task in order of submission in the ThreadPool's worker thread after the ThreadPool has been shut down

toString()

string Qore::Thread::ThreadPool::toString

(

)

returns a description of the ThreadPool

Code Flags:

CONSTANT

Example:

string desc = tp.toString();

Returns

a description of the ThreadPool