You.i Engine
CYIThreadPool Class Reference

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 State::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

#include <thread/YiThreadPool.h>

Public Member Functions

 CYIThreadPool (const CYIString &name="ThreadPool", size_t maxSize=4, size_t maxSleepingSize=4, size_t initialSize=2, uint32_t expiryTimeMs=30000, CYIThread::Priority priority=CYIThread::Priority::Default, size_t stackSize=CYIThread::DEFAULT_STACK_SIZE)
 
virtual ~CYIThreadPool ()
 
const CYIStringGetName () const
 
size_t GetSleepingThreadsCount () const
 
size_t GetThreadsCount () const
 
size_t GetPendingTasksCount () const
 
bool WaitUntilIdle (uint32_t timeoutMs=std::numeric_limits< uint32_t >::max()) const
 
bool Queue (std::unique_ptr< CYITaskBase > pTask)
 
template<typename Callable , typename... Args>
auto Queue (Callable callable, Args &&... args) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())>
 
template<typename ResultType , typename Callable , typename... Args>
bool Queue (CYIFuture< ResultType > future, Callable callable, Args &&... args)
 
template<typename Callable , typename... Args>
bool QueueAndForget (Callable callable, Args &&... args)
 
void Shutdown ()
 

Constructor & Destructor Documentation

◆ CYIThreadPool()

CYIThreadPool::CYIThreadPool ( const CYIString name = "ThreadPool",
size_t  maxSize = 4,
size_t  maxSleepingSize = 4,
size_t  initialSize = 2,
uint32_t  expiryTimeMs = 30000,
CYIThread::Priority  priority = CYIThread::Priority::Default,
size_t  stackSize = CYIThread::DEFAULT_STACK_SIZE 
)

Creates a new thread pool from the provided parameters.

Parameters
nameThe name of the thread pool. Created worker threads will have a name composed of the thread pool name and an ID number.
maxSizeThe maximum number of worker threads in the pool (both active and sleeping). If 0, a value of 1 will be used instead.
maxSleepingSizeThe 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.
initialSizeThe initial number of created worker threads. Note that if this number is lower than maxSleepingSize, the worker threads will be deleted shortly after creation of the thread pool.
expiryTimeMsIf non-zero, this will define the number of milliseconds before a sleeping worker thread is deleted when it is scheduled for deletion.
priorityThe worker thread priority.
stackSizeThe stack size of the worker threads.

◆ ~CYIThreadPool()

virtual CYIThreadPool::~CYIThreadPool ( )
virtual

Member Function Documentation

◆ GetName()

const CYIString& CYIThreadPool::GetName ( ) const
Returns
The name of this thread pool.

◆ GetPendingTasksCount()

size_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.

◆ GetSleepingThreadsCount()

size_t CYIThreadPool::GetSleepingThreadsCount ( ) const
Note
This function should be used for debugging purposes only.
Returns
The current number of sleeping worker threads.

◆ GetThreadsCount()

size_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.

◆ Queue() [1/3]

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 State::New state and if this thread pool has not yet been shut down.

Returns
Returns true if the provided task was successfully enqueued.

◆ Queue() [2/3]

template<typename Callable , typename... Args>
auto CYIThreadPool::Queue ( Callable  callable,
Args &&...  args 
) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())>

A helper function used to enqueue callable (a callable object) for execution in this thread pool, using the provided optional function arguments.

Note
The callable can optionally take a CYITaskBase pointer as first parameter. This allows the Callable to detect and respond to cancellation requests.
Returns
Returns a new CYIFuture object which can be used to receive the result of the callable's execution. Returns a cancelled CYIFuture if the thread pool has been shut down.

Examples:

pool.Queue([]()
{
// Continuation code
});
future.Queue([](CYITaskBase *pTask, std::vector<CYIString> values)
{
// Continuation code
}, vector);

◆ Queue() [3/3]

template<typename ResultType , typename Callable , typename... Args>
bool CYIThreadPool::Queue ( CYIFuture< ResultType >  future,
Callable  callable,
Args &&...  args 
)

A helper function used to enqueue callable (a callable object) for execution in this thread pool, using the provided optional function arguments. The queued task will be associated with future.

Note
The callable can optionally take a CYITaskBase pointer as first parameter. This allows the Callable to detect and respond to cancellation requests.
Returns
Returns true if the provided callable was successfully enqueued for execution.

◆ QueueAndForget()

template<typename Callable , typename... Args>
bool CYIThreadPool::QueueAndForget ( Callable  callable,
Args &&...  args 
)

A helper function used to enqueue callable (a callable object) for execution in this thread pool, using the provided optional function arguments.

Note
Unlike Queue(), this function does not allocate and return a CYIFuture instance.
Returns
Returns true if the provided callable was successfully enqueued.

◆ Shutdown()

void CYIThreadPool::Shutdown ( )

Shuts down this thread pool. All pending queued tasks will be cancelled and an attempt will be made at cancelling currently-executing tasks. The function will then block until all currently-executing tasks have completed and until all worker threads have been deleted.

◆ WaitUntilIdle()

bool CYIThreadPool::WaitUntilIdle ( uint32_t  timeoutMs = std::numeric_limits< uint32_t >::max()) const

Waits until there are no pending tasks and no currently-executing tasks in this thread pool.

Note
This function should be used for debugging purposes only.
Returns
Returns true if the threadpool is now idle, or false if the timeout was reached.

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