You.i Engine
CYIThreadPools Class Reference

Detailed Description

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:

bool MyView::Init()
{
{
return false;
}
m_future = CYIThreadPools::RunAsync(m_future, [](CYIString filename) {
FileData fileData = FileReader::ReadFile(filename);
return ImageDecoder::DecodeImage(fileData);
}], m_filename);
m_pFuture->Completed.Connect(*this, &MyView::OnImageDecoded);
}
MyView::~MyView()
{
m_future.Cancel(); // If not present, the task will continue executing even if MyView is deleted
}
void MyView::OnImageDecoded(const std::shared_ptr<ImageData> &pImageData)
{
m_pImageView->SetImage(pImageData);
}
See also
CYIThreadPool
CYITask
CYICallableTask
YiMakeTask()

#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 CYIThreadPoolGetDefaultThreadPool ()
 
static CYIThreadPoolGetManagedThreadPool (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

CYIThreadPoolInstanceGetDefaultThreadPool ()
 
CYIThreadPoolInstanceGetManagedThreadPool (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
 

Member Enumeration Documentation

◆ RunAsyncMode

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.

Constructor & Destructor Documentation

◆ CYIThreadPools()

CYIThreadPools::CYIThreadPools ( bool  instanciateDefaultPool = true,
uint32_t  defaultPoolThreadsCount = 0 
)

Creates a new CYIThreadPools object. This is typically done by the CYIFramework class only.

Parameters
instanciateDefaultPoolIf false, the CYIThreadPools object will be created without a default thread pool.
defaultPoolThreadsCountIf 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::~CYIThreadPools ( )

Member Function Documentation

◆ DestroyManagedThreadPool()

static bool CYIThreadPools::DestroyManagedThreadPool ( const CYIString name)
static

Causes the thread pool identified by the provided name to be shutdown and destroyed.

Note
Calling this function isn't strictly necessary as managed thread pools are automatically shutdown and destroyed when this class is shut down.
Returns
Returns true if thread pool was shutdown and destroyed; returns false if the thread pool with the provided name could not be located.

◆ GetDefaultPoolThreadsCount()

static uint32_t CYIThreadPools::GetDefaultPoolThreadsCount ( )
static
Returns
The number of worker threads that the default thread pool should use. This number is typically derived from the number of logical processors on the system.
See also
CYIThreadPools::GetDefaultThreadPool()
CYIThreadPools::GetLogicalProcessorsCount(bool)

◆ GetDefaultThreadPool()

static CYIThreadPool* CYIThreadPools::GetDefaultThreadPool ( )
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.

Note
It is recommended that only tasks that are processor-intensive be executed on the default system thread pool. Queueing blocking blocking tasks (e.g. tasks that wait on network) would result in processor ressources going unused as one of the worker threads is blocked. Instead, blocking tasks should be executed on a separate thread pool (which may or may not be tracked by this class) or on new threads.
If this class has been created without a default thread pool or if this class has been shut down, a null pointer is returned.
Returns
Returns a reference to the default thread pool.
See also
CYIThreadPools::GetDefaultPoolThreadsCount()

◆ GetLogicalProcessorsCount()

static uint32_t CYIThreadPools::GetLogicalProcessorsCount ( bool  usableProcessorsOnly)
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.

Parameters
usableProcessorsOnlyOn 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.
Returns
Returns the number of logical processors on the system. Returns 0 if the number of logical processors could not be determined.

◆ GetManagedThreadPool()

static CYIThreadPool* CYIThreadPools::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

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.

Note
Parameters other than the name are used only if a thread pool with the provided name could not be located.
If this class has not been initialized or if this class has been shut down, a null pointer is returned.
Parameters
nameThe 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.
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.
Returns
Returns the thread pool instance identified by the provided name.

◆ InstanceDestroyManagedThreadPool()

bool CYIThreadPools::InstanceDestroyManagedThreadPool ( const CYIString name)
protected

◆ InstanceGetDefaultThreadPool()

CYIThreadPool* CYIThreadPools::InstanceGetDefaultThreadPool ( )
protected

◆ InstanceGetManagedThreadPool()

CYIThreadPool* CYIThreadPools::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 
)
protected

◆ InstanceRunAsync()

bool CYIThreadPools::InstanceRunAsync ( std::unique_ptr< CYITaskBase pTask)
protected

◆ InstanceRunOnNewThread()

bool CYIThreadPools::InstanceRunOnNewThread ( std::unique_ptr< CYITaskBase pTask)
protected

◆ RunAsync() [1/5]

static bool CYIThreadPools::RunAsync ( std::unique_ptr< CYITaskBase pTask,
RunAsyncMode  runAsyncMode = RunAsyncMode::OnDefaultThreadPool 
)
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.

Returns
Returns true if the provided task was successfully enqueued.
See also
RunAsync(std::unique_ptr<CYITaskBase>, RunAsyncMode>

◆ RunAsync() [2/5]

template<typename Callable , typename... Args>
static auto CYIThreadPools::RunAsync ( Callable  callable,
Args &&...  args 
) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())>
static

Queues the callable object callable for (eventual) execution in the default system thread pool, using the provided optional parameters.

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 CYIFuture object which can be used to receive the result of the callable's execution. Returns a cancelled CYIFuture if the default thread pool has been shut down.

◆ RunAsync() [3/5]

template<typename Callable , typename... Args>
static auto CYIThreadPools::RunAsync ( Callable  callable,
RunAsyncMode  runAsyncMode,
Args &&...  args 
) -> CYIFuture< decltype(ReturnTypeOf< Callable, Args... >())>
static

Queues the callable object callable for (eventual) execution with the async mode runAsyncMode, using the provided optional parameters.

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 CYIFuture object which can be used to receive the result of the callable's execution. Returns a cancelled CYIFuture if the default thread pool has been shut down.

◆ RunAsync() [4/5]

template<typename ResultType , typename Callable , typename... Args>
static bool CYIThreadPools::RunAsync ( CYIFuture< ResultType >  future,
Callable  callable,
Args &&...  args 
)
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.

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.

◆ RunAsync() [5/5]

template<typename ResultType , typename Callable , typename... Args>
static bool CYIThreadPools::RunAsync ( CYIFuture< ResultType >  future,
Callable  callable,
RunAsyncMode  runAsyncMode,
Args &&...  args 
)
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.

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.

◆ RunAsyncAndForget() [1/2]

template<typename Callable , typename... Args>
static bool CYIThreadPools::RunAsyncAndForget ( Callable  callable,
Args &&...  args 
)
static

Queues the callable object callable for (eventual) execution in the default system thread pool, using the provided optional parameters.

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

◆ RunAsyncAndForget() [2/2]

template<typename Callable , typename... Args>
static bool CYIThreadPools::RunAsyncAndForget ( Callable  callable,
RunAsyncMode  runAsyncMode,
Args &&...  args 
)
static

Queues the callable object callable for (eventual) execution with the async mode runAsyncMode, using the provided optional parameters.

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

Friends And Related Function Documentation

◆ CYIThreadPoolsPriv

friend class CYIThreadPoolsPriv
friend

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