Diligent::IThreadPool Struct Reference

Thread pool interface. More...

#include <ThreadPool.h>

Inheritance diagram for Diligent::IThreadPool:

Public Member Functions
virtual void DILIGENT_CALL_TYPE	EnqueueTask (IAsyncTask *pTask, IAsyncTask **ppPrerequisites=nullptr, Uint32 NumPrerequisites=0)=0
	Enqueues asynchronous task for execution.
virtual bool DILIGENT_CALL_TYPE	ReprioritizeTask (IAsyncTask *pTask)=0
	Reprioritizes the task in the queue.
virtual void DILIGENT_CALL_TYPE	ReprioritizeAllTasks ()=0
	Reprioritizes all tasks in the queue.
virtual bool DILIGENT_CALL_TYPE	RemoveTask (IAsyncTask *pTask)=0
	Removes the task from the queue, if possible.
virtual void DILIGENT_CALL_TYPE	WaitForAllTasks ()=0
	Waits until all tasks in the queue are finished.
virtual Uint32 DILIGENT_CALL_TYPE	GetQueueSize ()=0
	Returns the current queue size.
virtual Uint32 DILIGENT_CALL_TYPE	GetRunningTaskCount () const =0
	Returns the number of currently running tasks.
virtual void DILIGENT_CALL_TYPE	StopThreads ()=0
	Stops all worker threads.
virtual bool DILIGENT_CALL_TYPE	ProcessTask (Uint32 ThreadId, bool WaitForTask)=0
	Manually processes the next task from the queue.
Public Member Functions inherited from Diligent.IObject
virtual void DILIGENT_CALL_TYPE	QueryInterface (const INTERFACE_ID &IID, IObject **ppInterface)=0
	Queries the specific interface.
virtual ReferenceCounterValueType DILIGENT_CALL_TYPE	AddRef ()=0
	Increments the number of strong references by 1.
virtual ReferenceCounterValueType DILIGENT_CALL_TYPE	Release ()=0
virtual IReferenceCounters *DILIGENT_CALL_TYPE	GetReferenceCounters () const =0

Detailed Description

Thread pool interface.

Member Function Documentation

EnqueueTask()

virtual void DILIGENT_CALL_TYPE Diligent::IThreadPool::EnqueueTask ( IAsyncTask * pTask, IAsyncTask ** ppPrerequisites = nullptr, Uint32 NumPrerequisites = 0 )

pure virtual

Enqueues asynchronous task for execution.

Parameters

[in]	pTask	- Task to run.
[in]	ppPrerequisites	- Array of task prerequisites, e.g. the tasks that must be completed before this task can start.
[in]	NumPrerequisites	- Number of prerequisites.

Thread pool will keep a strong reference to the task, so an application is free to release it after enqueuing.

Note

An application must ensure that the task prerequisites are not circular to avoid deadlocks.

ProcessTask()

virtual bool DILIGENT_CALL_TYPE Diligent::IThreadPool::ProcessTask ( Uint32 ThreadId, bool WaitForTask )

pure virtual

Manually processes the next task from the queue.

Parameters

[in]	ThreadId	- Id of the thread that is running this task.
[in]	WaitForTask	- whether the function should wait for the next task: if true, the function will block the thread until the next task is retrieved from the queue and processed. if false, the function will return immediately if there are no tasks in the queue.

Returns

Whether there are more tasks to process. The calling thread must keep calling the function until it returns false.

This method allows an application to implement its own threading strategy. A thread pool may be created with zero threads, and the application may call ProcessTask() method from its own threads.

An application must keep calling the method until it returns false. If there are unhandled tasks in the queue and the application stops processing them, the thread pool will hang up.

An example of handling the tasks is shown below:

// Initialization
auto pThreadPool = CreateThreadPool(ThreadPoolCreateInfo{0});

std::vector<std::thread> WorkerThreads(4);
for (Uint32 i PURE; i < WorkerThreads.size(); ++i)
{
    WorkerThreads[i] = std::thread{
        [&ThreadPool = *pThreadPool, i] //
        {
            while (ThreadPool.ProcessTask(i, true))
            {
            }
        }};
}

// Enqueue async tasks

pThreadPool->WaitForAllTasks();

// Stop all threads in the pool
pThreadPool->StopThreads();

// Cleanup (must be done after all threads are stopped)
for (auto& Thread : WorkerThreads)
{
    Thread.join();
}

RemoveTask()

virtual bool DILIGENT_CALL_TYPE Diligent::IThreadPool::RemoveTask ( IAsyncTask * pTask )

pure virtual

Removes the task from the queue, if possible.

Parameters

[in]

pTask

- Task to remove from the queue.

Returns

true if the task was successfully removed from the queue, and false otherwise.

ReprioritizeAllTasks()

virtual void DILIGENT_CALL_TYPE Diligent::IThreadPool::ReprioritizeAllTasks ( )

pure virtual

Reprioritizes all tasks in the queue.

This method should be called if task priorities have changed to update the positions of all tasks in the queue.

ReprioritizeTask()

virtual bool DILIGENT_CALL_TYPE Diligent::IThreadPool::ReprioritizeTask ( IAsyncTask * pTask )

pure virtual

Reprioritizes the task in the queue.

Parameters

[in]

pTask

- Task to reprioritize.

Returns

true if the task was found in the queue and was successfully reprioritized, and false otherwise.

When the tasks is enqueued, its priority is used to place it in the priority queue. When an application changes the task priority, it should call this method to update the task position in the queue.

StopThreads()

virtual void DILIGENT_CALL_TYPE Diligent::IThreadPool::StopThreads ( )

pure virtual

Stops all worker threads.

his method makes all worker threads to exit. If an application enqueues tasks after calling this methods, this tasks will never run.

WaitForAllTasks()

virtual void DILIGENT_CALL_TYPE Diligent::IThreadPool::WaitForAllTasks ( )

pure virtual

Waits until all tasks in the queue are finished.

The method blocks the calling thread until all tasks in the quque are finished and the queue is empty. An application is responsible to make sure that all tasks will finish eventually.