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 tasks and Future objects:

bool MyView::Init()
{
   if (!CYISceneView::Init())
   {
       return false;
   }
   m_pFuture = new CYIFuture<std::shared_ptr<ImageData> >();
   m_pFuture->Completed.Connect(*this, &MyView::OnImageDecoded);
   CYITask<std::shared_ptr<ImageData> > *pTask = new CYIStaticTask<std::shared_ptr<ImageData> >(*m_pFuture, &MyView::DecodeImage, CYIString("MyFileName"));
   CYIThreadPools::RunAsync(pTask);
}
MyView::~MyView()
{
   delete m_pFuture; // will cancel the task if it hasn’t run
}
static std::shared_ptr<ImageData> MyView::DecodeImage(const CYIString filename)
{
   FileData fileData = FileReader::ReadFile(filename);
   return ImageDecoder::DecodeImage(fileData);
}
void MyView::OnImageDecoded(const std::shared_ptr<ImageData> &rImageData)
{
   m_pImageView->SetImage(rImageData);
}

See also: CYIThreadPool; CYITask<ResultType>

#include <thread/YiThreadPools.h>

Public Member Functions
	CYIThreadPools (bool bInstanciateDefaultPool=true, uint32_t uDefaultPoolThreadsCount=0)

	~CYIThreadPools ()

CYIThreadPool *	InstanceGetDefaultThreadPool ()

CYIThreadPool *	InstanceGetManagedThreadPool (const CYIString &name, 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)

bool	InstanceDestroyManagedThreadPool (const CYIString &name)

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

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

Static Public Member Functions
static CYIThreadPool *	GetDefaultThreadPool ()

static CYIThreadPool *	GetManagedThreadPool (const CYIString &name, 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)

static bool	DestroyManagedThreadPool (const CYIString &name)

static uint32_t	GetDefaultPoolThreadsCount ()

static uint32_t	GetLogicalProcessorsCount (bool bUsableProcessorsOnly)
	returns 0 if the processors count could not be determined More...

static bool	RunOnNewThread (std::unique_ptr< CYITaskBase > pTask)

static bool	RunOnUIThread (std::unique_ptr< CYITaskBase > pTask)

static bool	RunAsync (std::unique_ptr< CYITaskBase > pTask)

Constructor & Destructor Documentation

CYIThreadPools::CYIThreadPools	(	bool	bInstanciateDefaultPool = `true`,
		uint32_t	uDefaultPoolThreadsCount = `0`
	)

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

Parameters

bInstanciateDefaultPool	If false, the CYIThreadPools object will be created without a default thread pool.
uDefaultPoolThreadsCount	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 ( )

Member Function Documentation

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.

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)

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

static uint32_t CYIThreadPools::GetLogicalProcessorsCount ( bool bUsableProcessorsOnly )

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

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

static CYIThreadPool* CYIThreadPools::GetManagedThreadPool	(	const CYIString &	name,
		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`
	)

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

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

bool CYIThreadPools::InstanceDestroyManagedThreadPool ( const CYIString & name )

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

CYIThreadPool* CYIThreadPools::InstanceGetDefaultThreadPool ( )

See also: CYIThreadPool::GetDefaultThreadPool()

CYIThreadPool* CYIThreadPools::InstanceGetManagedThreadPool	(	const CYIString &	name,
		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`
	)

See also: CYIThreadPool::GetManagedThreadPool(const CYIString&)

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

See also: CYIThreadPool::RunAsync(CYITaskBase *pTask)

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

See also: CYIThreadPool::RunOnNewThread(CYITaskBase *pTask)

static bool CYIThreadPools::RunAsync ( std::unique_ptr< CYITaskBase > pTask )

static

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

Tasks can only be enqueued if they are in the TASK_NEW state and if this class has been initialized.

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

static bool CYIThreadPools::RunOnNewThread ( std::unique_ptr< CYITaskBase > pTask )

static

Queues the provided task for (eventual) execution on a new thread.

Tasks can only be enqueued if they are in the TASK_NEW state and if this class has been initialized.

Note: Once execution has completed, the created thread will be destroyed by a new task in the default thread pool.

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

static bool CYIThreadPools::RunOnUIThread ( std::unique_ptr< CYITaskBase > pTask )

static

Queues the provided task for (eventual) execution on the system's UI thread.

Tasks can only be enqueued if they are in the TASK_NEW state and if the default event dispatcher exists.

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

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

thread/YiThreadPools.h

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation