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()
{
   if (!CYISceneView::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 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

Member Enumeration Documentation

◆ RunAsyncMode

enum CYIThreadPools::RunAsyncMode

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.

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

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

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.

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

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.

Returns: Returns the thread pool instance identified by the provided name.

◆ InstanceDestroyManagedThreadPool()

bool CYIThreadPools::InstanceDestroyManagedThreadPool ( const CYIString & name )

protected

See also: CYIThreadPools::DestroyManagedThreadPool(const CYIString &name)

◆ InstanceGetDefaultThreadPool()

CYIThreadPool* CYIThreadPools::InstanceGetDefaultThreadPool ( )

protected

See also: CYIThreadPools::GetDefaultThreadPool()

◆ 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

See also: CYIThreadPools::GetManagedThreadPool

◆ InstanceRunAsync()

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

protected

See also: CYIThreadPools::RunAsync(std::unique_ptr<CYITaskBase>, RunAsyncMode)

◆ InstanceRunOnNewThread()

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

protected

See also: CYIThreadPools::RunAsync(std::unique_ptr<CYITaskBase>, RunAsyncMode)

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

thread/YiThreadPools.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Member Enumeration Documentation

◆ RunAsyncMode

Constructor & Destructor Documentation

◆ CYIThreadPools()

◆ ~CYIThreadPools()

Member Function Documentation

◆ DestroyManagedThreadPool()

◆ GetDefaultPoolThreadsCount()

◆ GetDefaultThreadPool()

◆ GetLogicalProcessorsCount()

◆ GetManagedThreadPool()

◆ InstanceDestroyManagedThreadPool()

◆ InstanceGetDefaultThreadPool()

◆ InstanceGetManagedThreadPool()

◆ InstanceRunAsync()

◆ InstanceRunOnNewThread()

◆ RunAsync() [1/5]

◆ RunAsync() [2/5]

◆ RunAsync() [3/5]

◆ RunAsync() [4/5]

◆ RunAsync() [5/5]

◆ RunAsyncAndForget() [1/2]

◆ RunAsyncAndForget() [2/2]

Friends And Related Function Documentation

◆ CYIThreadPoolsPriv