Detailed Description

A thread pool manages one or more threads and uses them to execute queued tasks.

Various parameters are specified at construction-time to specify how worker threads are created and destroyed. Created worker threads will have a name prefixed with the thread pool name.

When a pool is destroyed, all queued non-running tasks are cancelled and an attempt is made at cancelling currently-executing tasks. The pool then waits until all currently-executing tasks complete their execution.

Note: All functions that take a task as input will result in the pool taking ownership of the provided task. The only exception to this is if a task is provided that is in a state other than TASK_NEW. This is to avoid a possible double-deletion when the pool attempts to delete the task.; If a thread pool is created with a maximum worker threads count larger than 1, there will be no guarantee as to the order in which queued tasks are executed. For example, if a user queues Task A for execution in the thread pool and then queues Task B, Task B may be executed prior to Task A.

See also: CYIThreadPools; CYITask<ResultType>

#include <thread/YiThreadPool.h>

Public Member Functions
	CYIThreadPool (const CYIString &sName="ThreadPool", uint32_t uMaxSize=4, uint32_t uMaxSleepingSize=4, uint32_t uInitialSize=2, uint32_t uExpiryTimeMs=30000, YI_PRIORITY ePriority=YI_PRIORITY_DEFAULT, uint32_t uStackSize=CYIThread::DEFAULT_STACK_SIZE)

virtual	~CYIThreadPool ()

const CYIString &	GetName () const

uint32_t	GetSleepingThreadsCount () const

uint32_t	GetThreadsCount () const

uint32_t	GetPendingTasksCount () const

bool	Queue (std::unique_ptr< CYITaskBase > pTask)

void	Shutdown ()

template<typename ResultType >
std::unique_ptr< CYIFuture< ResultType > >	Queue (ResultType(*const pFunc)())

template<typename ResultType , typename P1 >
std::unique_ptr< CYIFuture< ResultType > >	Queue (ResultType(*const pFunc)(P1), P1 const &funcParam1)

template<typename ResultType , typename P1 , typename P2 >
std::unique_ptr< CYIFuture< ResultType > >	Queue (ResultType(*const pFunc)(P1, P2), P1 const &funcParam1, P2 const &funcParam2)

template<typename ResultType , typename P1 , typename P2 , typename P3 >
std::unique_ptr< CYIFuture< ResultType > >	Queue (ResultType(*const pFunc)(P1, P2, P3), P1 const &funcParam1, P2 const &funcParam2, P3 const &funcParam3)

template<typename ResultType , typename P1 , typename P2 , typename P3 , typename P4 >
std::unique_ptr< CYIFuture< ResultType > >	Queue (ResultType(*const pFunc)(P1, P2, P3, P4), P1 const &funcParam1, P2 const &funcParam2, P3 const &funcParam3, P4 const &funcParam4)

template<typename ResultType >
bool	QueueAndForget (ResultType(*const pFunc)())

template<typename ResultType , typename P1 >
bool	QueueAndForget (ResultType(*const pFunc)(P1), P1 const &funcParam1)

template<typename ResultType , typename P1 , typename P2 >
bool	QueueAndForget (ResultType(*const pFunc)(P1, P2), P1 const &funcParam1, P2 const &funcParam2)

template<typename ResultType , typename P1 , typename P2 , typename P3 >
bool	QueueAndForget (ResultType(*const pFunc)(P1, P2, P3), P1 const &funcParam1, P2 const &funcParam2, P3 const &funcParam3)

template<typename ResultType , typename P1 , typename P2 , typename P3 , typename P4 >
bool	QueueAndForget (ResultType(*const pFunc)(P1, P2, P3, P4), P1 const &funcParam1, P2 const &funcParam2, P3 const &funcParam3, P4 const &funcParam4)

Constructor & Destructor Documentation

CYIThreadPool::CYIThreadPool	(	const CYIString &	sName = `"ThreadPool"`,
		uint32_t	uMaxSize = `4`,
		uint32_t	uMaxSleepingSize = `4`,
		uint32_t	uInitialSize = `2`,
		uint32_t	uExpiryTimeMs = `30000`,
		YI_PRIORITY	ePriority = `YI_PRIORITY_DEFAULT`,
		uint32_t	uStackSize = `CYIThread::DEFAULT_STACK_SIZE`
	)

Creates a new thread pool from the provided parameters.

Parameters

sName	The name of the thread pool. Created worker threads will have a name composed of the thread pool name and an ID number.
uMaxSize	The maximum number of worker threads in the pool (both active and sleeping). If 0, a value of 1 will be used instead.
uMaxSleepingSize	The maximum number of worker threads that can be in the 'sleeping' state (e.g. when no tasks are available for execution). If the number of sleeping worker threads is larger than this number, the extra worker threads will be deleted.
uInitialSize	The initial number of created worker threads. Note that if this number is lower than uMaxSleepingSize, the worker threads will be deleted shortly after creation of the thread pool.
uExpiryTimeMs	If non-zero, this will define the number of milliseconds before a sleeping worker thread is deleted when it is scheduled for deletion.
ePriority	The worker thread priority.
uStackSize	The stack size of the worker threads.

virtual CYIThreadPool::~CYIThreadPool ( )

virtual

Member Function Documentation

const CYIString& CYIThreadPool::GetName ( ) const

Returns: The name of this thread pool.

uint32_t CYIThreadPool::GetPendingTasksCount ( ) const

Note: This function should be used for debugging purposes only.

Returns: The current number of tasks pending execution. This does not include currently-executing tasks.

uint32_t CYIThreadPool::GetSleepingThreadsCount ( ) const

Note: This function should be used for debugging purposes only.

Returns: The current number of sleeping worker threads.

uint32_t CYIThreadPool::GetThreadsCount ( ) const

Note: This function should be used for debugging purposes only.

Returns: The current number of worker threads. This includes both active and sleeping worker threads.

bool CYIThreadPool::Queue ( std::unique_ptr< CYITaskBase > pTask )

Queues the provided task for (eventual) execution in this thread pool.

Tasks can only be enqueued if they are in the TASK_NEW state and if this thread pool has not yet been shut down.

Returns: Returns true if the provided task was successfully enqueued.

template<typename ResultType >

std::unique_ptr<CYIFuture<ResultType> > CYIThreadPool::Queue ( ResultType(*)() pFunc )

A helper function used to enqueue pFunc (a static function) for execution in this thread pool.

Returns: Returns a new CYIFuture object which can be used to receive the result of the function's execution. Returns a null pointer if the thread pool has been shut down.

template<typename ResultType , typename P1 >

std::unique_ptr<CYIFuture<ResultType> > CYIThreadPool::Queue	(	ResultType(*)(P1)	pFunc,
		P1 const &	funcParam1
	)

A helper function used to enqueue pFunc (a static function) for execution in this thread pool, using the provided function argument. funcParam1 is passed to the static function.

Warning: The caller must take ownership of the returned CYIFuture object or a memory leak will occur.

Returns: Returns a new CYIFuture object which can be used to receive the result of the function's execution. Returns a null pointer if the thread pool has been shut down.

template<typename ResultType , typename P1 , typename P2 >

std::unique_ptr<CYIFuture<ResultType> > CYIThreadPool::Queue	(	ResultType(*)(P1, P2)	pFunc,
		P1 const &	funcParam1,
		P2 const &	funcParam2
	)

A helper function used to enqueue pFunc (a static function) for execution in this thread pool, using the provided function arguments. funcParam1, funcParam2 are passed to the static function.

Warning: The caller must take ownership of the returned CYIFuture object or a memory leak will occur.

Returns: Returns a new CYIFuture object which can be used to receive the result of the function's execution. Returns a null pointer if the thread pool has been shut down.

template<typename ResultType , typename P1 , typename P2 , typename P3 >

std::unique_ptr<CYIFuture<ResultType> > CYIThreadPool::Queue	(	ResultType(*)(P1, P2, P3)	pFunc,
		P1 const &	funcParam1,
		P2 const &	funcParam2,
		P3 const &	funcParam3
	)

A helper function used to enqueue pFunc (a static function) for execution in this thread pool, using the provided function arguments. funcParam1, funcParam2, funcParam3 are passed to the static function.

Warning: The caller must take ownership of the returned CYIFuture object or a memory leak will occur.

Returns: Returns a new CYIFuture object which can be used to receive the result of the function's execution. Returns a null pointer if the thread pool has been shut down.

template<typename ResultType , typename P1 , typename P2 , typename P3 , typename P4 >

std::unique_ptr<CYIFuture<ResultType> > CYIThreadPool::Queue	(	ResultType(*)(P1, P2, P3, P4)	pFunc,
		P1 const &	funcParam1,
		P2 const &	funcParam2,
		P3 const &	funcParam3,
		P4 const &	funcParam4
	)

A helper function used to enqueue pFunc (a static function) for execution in this thread pool, using the provided function arguments. funcParam1, funcParam2, funcParam3, funcParam4 are passed to the static function.

Warning: The caller must take ownership of the returned CYIFuture object or a memory leak will occur.

Returns: Returns a new CYIFuture object which can be used to receive the result of the function's execution. Returns a null pointer if the thread pool has been shut down.