A class used to initialize, manage and destroy system-managed thread pools. Convenience functions to enqueue tasks are also provided.
When initialized, this class creates a default system thread pool. This pool has a fixed number of worker threads whose count matches the number of logical processors on the system.
This class also allows users to create user-defined thread pools, which are then managed by this class. The same pools can be accessed by multiple users through this class.
When this class is shutdown, all managed thread pools are shut down and destroyed.
Follows is a code sample that shows how thread pools can be used along with Future objects:
#include <thread/YiThreadPools.h>
Public Types | |
enum | RunAsyncMode { RunAsyncMode::OnDefaultThreadPool, RunAsyncMode::OnUIThread, RunAsyncMode::OnUIThreadOrSynchronously, RunAsyncMode::OnNewThread, RunAsyncMode::Synchronously } |
An enum that lists the various async running modes for use with the RunAsync() functions. More... | |
Public Member Functions | |
CYIThreadPools (bool instanciateDefaultPool=true, uint32_t defaultPoolThreadsCount=0) | |
~CYIThreadPools () | |
Static Public Member Functions | |
static CYIThreadPool * | GetDefaultThreadPool () |
static CYIThreadPool * | GetManagedThreadPool (const CYIString &name, 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) |
static bool | DestroyManagedThreadPool (const CYIString &name) |
static uint32_t | GetDefaultPoolThreadsCount () |
static uint32_t | GetLogicalProcessorsCount (bool usableProcessorsOnly) |
returns 0 if the processors count could not be determined More... | |
static bool | RunAsync (std::unique_ptr< CYITaskBase > pTask, RunAsyncMode runAsyncMode=RunAsyncMode::OnDefaultThreadPool) |
template<typename Callable , typename... Args> | |
static auto | RunAsync (Callable callable, Args &&... args) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())> |
template<typename Callable , typename... Args> | |
static auto | RunAsync (Callable callable, RunAsyncMode runAsyncMode, Args &&... args) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())> |
template<typename ResultType , typename Callable , typename... Args> | |
static bool | RunAsync (CYIFuture< ResultType > future, Callable callable, Args &&... args) |
template<typename ResultType , typename Callable , typename... Args> | |
static bool | RunAsync (CYIFuture< ResultType > future, Callable callable, RunAsyncMode runAsyncMode, Args &&... args) |
template<typename Callable , typename... Args> | |
static bool | RunAsyncAndForget (Callable callable, Args &&... args) |
template<typename Callable , typename... Args> | |
static bool | RunAsyncAndForget (Callable callable, RunAsyncMode runAsyncMode, Args &&... args) |
Protected Member Functions | |
CYIThreadPool * | InstanceGetDefaultThreadPool () |
CYIThreadPool * | InstanceGetManagedThreadPool (const CYIString &name, 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) |
bool | InstanceDestroyManagedThreadPool (const CYIString &name) |
bool | InstanceRunOnNewThread (std::unique_ptr< CYITaskBase > pTask) |
bool | InstanceRunAsync (std::unique_ptr< CYITaskBase > pTask) |
Friends | |
class | CYIThreadPoolsPriv |
|
strong |
An enum that lists the various async running modes for use with the RunAsync() functions.
Enumerator | |
---|---|
OnDefaultThreadPool | Runs the task (or callable object) on the default thread pool. This is the default mode for the RunAsync() functions. |
OnUIThread | Runs the task (or callable object) on the UI thread. This is sometimes called 'run on next frame'. Requesting this from the UI thread followed by Get(), Take() or Wait() will block the UI thread. By blocking the UI thread, a deadlock is created because the requested task never gets executed. To avoid this issue, OnUIThreadOrSynchronously should be used instead. |
OnUIThreadOrSynchronously | Runs the task (or callable object) on the UI thread. If the caller thread is the UI thread, it will run the task/callable before returning. This one is needed because requesting to run the task as RunAsyncMode::OnUIThread from the UI thread followed by Get(), Take() or Wait() will block the UI thread. By blocking the UI thread, a deadlock is created because the requested task never gets executed. |
OnNewThread | Runs the task (or callable object) on a newly-spawned thread. The thread is deleted after the task has run. |
Synchronously | Runs the task (or callable object) synchronously on the current thread. This is mostly used for testing, but can also be used in generic code. |
CYIThreadPools::CYIThreadPools | ( | bool | instanciateDefaultPool = true , |
uint32_t | defaultPoolThreadsCount = 0 |
||
) |
Creates a new CYIThreadPools object. This is typically done by the CYIFramework class only.
instanciateDefaultPool | If false, the CYIThreadPools object will be created without a default thread pool. |
defaultPoolThreadsCount | If non-0, the default thread pool will be created with an amount of threads equal to the provided value instead of using the number of available logical processors. |
CYIThreadPools::~CYIThreadPools | ( | ) |
|
static |
Causes the thread pool identified by the provided name to be shutdown and destroyed.
|
static |
|
static |
Returns a reference to the default system thread pool. This thread pool is created with a fixed number of worker threads, with a threads count equal to the number of logical processors on the system. Threads do not get destroyed when no tasks are available.
|
static |
returns 0 if the processors count could not be determined
Returns the number of logical processors present on the system.
The number of logical processors refers to how many hardware threads can be run concurrently. The differences between logical processors and 'real' processors depend on the system, but typically two or more logical processors share ressources that can only be accessed by one thread at a time. For example, a single-core hyperthreaded processor has one 'real' processor and two logical processors. On a system with a single-core hyperthreaded processor, two threads can be executed at the same time, but they would be sharing a single cache.
usableProcessorsOnly | On some systems, one or more logical processors are reserved by the operating system. If this parameter is true, only non-reserved logical processors are counted and returned. |
|
static |
Returns a refernece to the thread pool identified by the provided name. If no such thread pool exists, a new thread pool is created and returned.
Created thread pools are tracked by this class and automatically shutdown and destroyed when this class is shut down.
name | The name of the thread pool. Created worker threads will have a name composed of the thread pool name and an ID number. The name is also used to track and retrieve previously-created thread pools. |
maxSize | The maximum number of worker threads in the pool (both active and sleeping). If 0, a value of 1 will be used instead. |
maxSleepingSize | 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. |
initialSize | The 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. |
expiryTimeMs | If non-zero, this will define the number of milliseconds before a sleeping worker thread is deleted when it is scheduled for deletion. |
priority | The worker thread priority. |
stackSize | The stack size of the worker threads. |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
static |
Queues the provided task for (eventual) execution with the async mode runAsyncMode. By default, the task will run on the default system thread pool.
Tasks can only be enqueued if they are in the State::New state and if this class has been initialized.
|
static |
Queues the callable object callable for (eventual) execution in the default system thread pool, using the provided optional parameters.
|
static |
Queues the callable object callable for (eventual) execution with the async mode runAsyncMode, using the provided optional parameters.
|
static |
Queues the callable object callable for (eventual) execution in the default system thread pool, using the provided optional parameters. The queued task will be associated with future.
|
static |
Queues the callable object callable for (eventual) execution with the async mode runAsyncMode, using the provided optional parameters. The queued task will be associated with future.
|
static |
Queues the callable object callable for (eventual) execution in the default system thread pool, using the provided optional parameters.
|
static |
Queues the callable object callable for (eventual) execution with the async mode runAsyncMode, using the provided optional parameters.
|
friend |