Task queues holds tasks ready for execution by TaskWorkers. More...

Public Member Functions
	TaskQueue (TaskQueueId id, std::string_view name, size_t numThreads)
	Construct a TaskQueue instance with the given id and name.

	TaskQueue (const TaskQueue &)=delete

TaskQueue &	operator= (const TaskQueue &)=delete

	~TaskQueue ()
	Destructs a TaskQueue.

Task *	createTask (const TaskFunction func, ElementHandle &handle, const TaskId parentTaskId=nullptr)
	Creates a new task.

Task *	getTask (const TaskId &taskId)
	Get the task with the given id from the pool.

void	destroy (const TaskId &taskId)
	Destroy the task with the given id.

TaskId	create (TaskFunctionRef func)
	Create a task wrapping the given function.

TaskId	createGroup ()
	Create a task group.

TaskId	create (TaskFunctionRef func, const TaskId &parentTask)
	Create a task wrapping the given function, parented to the given parent task.

void	enqueueTask (Task *task)
	Enqueue the given task, executing it whenever a worker thread in the queue is available.

void	enqueue (const TaskId &taskId)
	Fetch the task with the given task id and enqueue it.

TaskId	enqueue (TaskFunctionRef func)
	Enqueue the given func object in the queue by creating a new Task with the function as work kernel.

TaskId	enqueue (TaskFunctionRef func, const TaskId &parentTaskId)
	Enqueue the given func object in the queue by creating a new Task with the function as work kernel.

Task *	getNextTask ()
	Get the next available Task from the task queue to execute.

Task *	getAvailableTask ()
	Gets a task from the task queue, or returns nullptr if no available task is found.

bool	canExecute (const Task *task) const
	Check if the given task is ready to be executed.

void	workOnTask (Task *task)
	Perform work on the given task.

void	yield ()
	Yield the currently executing thread to perform work on other available tasks or simply give back execution resources to the OS.

void	finishTask (Task *task)
	Finish the given task, returning the Task instance to the TaskPool and removing it from the set of active tasks for this queue.

void	destroyTask (Task *task)
	Destroy the given task, deallocating it from the task pool and freeing up any held resources.

bool	isActive (const TaskId &taskId)

void	wait (const TaskId &taskId)
	Wait on the task given by taskId.

void	waitAll ()
	Wait for all enqueued tasks to finish.

size_t	getConcurrency () const

TaskQueueId	getId () const

const std::string &	getName () const

void	getQueueState (QueueState &queueState, std::vector< QueueWorkerState > &workerStates) const

void	updateState (Context *context)

Private Member Functions
void	initializeWorkers ()
	Initialize TaskWorker instances.

Private Attributes
Timer	timer = Timer::startNew()

uint32_t	lastFrame = 0

QueueState	queueState {}

std::vector< QueueWorkerState >	workerStates
	Aggregated worker state data.

std::unique_ptr< std::vector< QueueWorkerStateData > >	workerStateData
	Tracks worker thread kernel launches continuosly.

TaskPool	taskPool
	Task pool holding Task instances.s.

std::string	name
	Name of the queue used for debugging.

Atomic< int >	active {0}
	Number of currently active tasks.

bool	done = false
	If the queue is done and should stop executing tasks.

Atomic< uint16_t >	generation = 0
	Generation counter used to track task lifetime.

std::queue< Task * >	taskQueue
	Currently queued tasks, ready for execution by a TaskWorker.

Mutex	poolMutex
	TaskPool mutex.

Mutex	taskMutex
	Task queue mutex.

std::condition_variable	taskVariable
	Condition variable used to signal tasks available for execution.

TaskQueueId	id {0}
	Id of the task queue.

std::vector< Thread >	threads
	Array of threads used to execute TaskWorker instances.

Detailed Description

Task queues holds tasks ready for execution by TaskWorkers.

Each task queue has a set of TaskWorker instances which will retrieve queued tasks and execute them on their designated threads.

Definition at line 101 of file TaskManager.cpp.

Constructor & Destructor Documentation

◆ TaskQueue()

Cogs::Core::TaskQueue::TaskQueue	(	TaskQueueId	id,
		std::string_view	name,
		size_t	numThreads
	)

inline

Construct a TaskQueue instance with the given id and name.

The queue name is used to identify threads belonging to the workers of this queue, for example when debugging.

Definition at line 110 of file TaskManager.cpp.

References initializeWorkers().

◆ ~TaskQueue()

Cogs::Core::TaskQueue::~TaskQueue ( )

inline

Destructs a TaskQueue.

Terminates all workers and threads before returning.

Definition at line 121 of file TaskManager.cpp.

References done, taskMutex, taskVariable, and threads.

Member Function Documentation

◆ canExecute()

bool Cogs::Core::TaskQueue::canExecute ( const Task * task ) const

inline

Check if the given task is ready to be executed.

Only tasks with an active count of 1 are eligible for execution. This means parent tasks with running child tasks are not available for execution until all child tasks finish running.

Parameters

task	Pointer to the task to check.

Definition at line 376 of file TaskManager.cpp.

References Cogs::Core::Task::active.

Referenced by workOnTask().

◆ create() [1/2]

TaskId Cogs::Core::TaskQueue::create ( TaskFunctionRef func )

inline

Create a task wrapping the given function.

Definition at line 226 of file TaskManager.cpp.

References createTask(), and Cogs::Core::TaskId::generation.

◆ create() [2/2]

TaskId Cogs::Core::TaskQueue::create	(	TaskFunctionRef	func,
		const TaskId &	parentTask
	)

inline

Create a task wrapping the given function, parented to the given parent task.

Definition at line 250 of file TaskManager.cpp.

References createTask(), and Cogs::Core::TaskId::generation.

◆ createGroup()

TaskId Cogs::Core::TaskQueue::createGroup ( )

inline

Create a task group.

Definition at line 238 of file TaskManager.cpp.

References createTask(), and Cogs::Core::TaskId::generation.

◆ createTask()

Task * Cogs::Core::TaskQueue::createTask	(	const TaskFunction *	func,
		ElementHandle &	handle,
		const TaskId *	parentTaskId = `nullptr`
	)

inline

Creates a new task.

If no function is given a task group is created.

Definition at line 139 of file TaskManager.cpp.

References Cogs::Core::Task::active, active, Cogs::Collections::Pool< ElementType >::create(), Cogs::Core::Task::flags, Cogs::Core::Task::generation, generation, Cogs::Collections::Pool< ElementType >::getHandle(), getTask(), Cogs::Core::Task::kernel, Cogs::Core::Task::parent, poolMutex, and taskPool.

Referenced by create(), createGroup(), and enqueue().

◆ destroy()

void Cogs::Core::TaskQueue::destroy ( const TaskId & taskId )

inline

Destroy the task with the given id.

The task is allowed to run until completion before being removed from the task pool.

Definition at line 205 of file TaskManager.cpp.

References destroyTask(), Cogs::Core::TaskId::generation, getTask(), and wait().

◆ destroyTask()

void Cogs::Core::TaskQueue::destroyTask ( Task * task )

inline

Destroy the given task, deallocating it from the task pool and freeing up any held resources.

Definition at line 468 of file TaskManager.cpp.

References Cogs::Core::Task::active, active, Cogs::Collections::Pool< ElementType >::destroy(), Cogs::Core::Task::flags, Cogs::Core::Task::generation, generation, poolMutex, and taskPool.

Referenced by destroy(), and finishTask().

◆ enqueue() [1/3]

void Cogs::Core::TaskQueue::enqueue ( const TaskId & taskId )

inline

Fetch the task with the given task id and enqueue it.

Definition at line 280 of file TaskManager.cpp.

References enqueueTask(), and getTask().

◆ enqueue() [2/3]

TaskId Cogs::Core::TaskQueue::enqueue ( TaskFunctionRef func )

inline

Enqueue the given func object in the queue by creating a new Task with the function as work kernel.

The function will be executed whenever a TaskWorker instance becomes available and previously queued Task instances are removed from the queue.

Parameters

func	Functor to assign as work kernel for the task.

Returns: A TaskId instance containing the information needed to reference the Task created at a later time.

Definition at line 294 of file TaskManager.cpp.

References createTask(), enqueueTask(), Cogs::Core::Task::generation, and threads.

◆ enqueue() [3/3]

TaskId Cogs::Core::TaskQueue::enqueue	(	TaskFunctionRef	func,
		const TaskId &	parentTaskId
	)

inline

Enqueue the given func object in the queue by creating a new Task with the function as work kernel.

The function will be executed whenever a TaskWorker instance becomes available and previously queued Task instances are removed from the queue. The given parent task is associated with the task.

Parameters

func	Functor to assign as work kernel for the task.
parentTaskId	Task id of the parent task.

Returns: A TaskId instance containing the information needed to reference the Task created at a later time.

Definition at line 318 of file TaskManager.cpp.

References createTask(), enqueueTask(), Cogs::Core::Task::generation, and threads.

◆ enqueueTask()

void Cogs::Core::TaskQueue::enqueueTask ( Task * task )

inline

Enqueue the given task, executing it whenever a worker thread in the queue is available.

Definition at line 262 of file TaskManager.cpp.

References finishTask(), Cogs::Core::Task::kernel, taskMutex, taskQueue, taskVariable, and threads.

Referenced by enqueue().

◆ finishTask()

void Cogs::Core::TaskQueue::finishTask ( Task * task )

inline

Finish the given task, returning the Task instance to the TaskPool and removing it from the set of active tasks for this queue.

Parameters

task	Pointer to a currently active task, which will be deactivated and deallocated.

Definition at line 440 of file TaskManager.cpp.

References Cogs::Core::Task::active, destroyTask(), finishTask(), Cogs::Core::Task::flags, and Cogs::Core::Task::parent.

Referenced by enqueueTask(), finishTask(), and workOnTask().

◆ getAvailableTask()

Task * Cogs::Core::TaskQueue::getAvailableTask ( )

inline

Gets a task from the task queue, or returns nullptr if no available task is found.

Definition at line 355 of file TaskManager.cpp.

References taskMutex, and taskQueue.

Referenced by yield().

◆ getConcurrency()

size_t Cogs::Core::TaskQueue::getConcurrency ( ) const

inline

Definition at line 533 of file TaskManager.cpp.

◆ getId()

TaskQueueId Cogs::Core::TaskQueue::getId ( ) const

inline

Definition at line 538 of file TaskManager.cpp.

◆ getName()

const std::string & Cogs::Core::TaskQueue::getName ( ) const

inline

Definition at line 543 of file TaskManager.cpp.

◆ getNextTask()

Task * Cogs::Core::TaskQueue::getNextTask ( )

inline

Get the next available Task from the task queue to execute.

Returns: Pointer to a task to execute, or nullptr if no more tasks will be available.

Definition at line 337 of file TaskManager.cpp.

References done, taskMutex, taskQueue, and taskVariable.

Referenced by Cogs::Core::TaskWorker::operator()().

◆ getQueueState()

void Cogs::Core::TaskQueue::getQueueState	(	QueueState &	queueState,
		std::vector< QueueWorkerState > &	workerStates
	)		const

inline

Definition at line 548 of file TaskManager.cpp.

◆ getTask()

Task * Cogs::Core::TaskQueue::getTask ( const TaskId & taskId )

inline

Get the task with the given id from the pool.

Definition at line 194 of file TaskManager.cpp.

References poolMutex, Cogs::Core::TaskId::taskHandle, and taskPool.

Referenced by createTask(), destroy(), enqueue(), and wait().

◆ initializeWorkers()

void Cogs::Core::TaskQueue::initializeWorkers ( )

private

Initialize TaskWorker instances.

Initializes worker threads and TaskWorker instances for the task queue.

Definition at line 673 of file TaskManager.cpp.

References name, threads, workerStateData, and workerStates.

Referenced by TaskQueue().

◆ isActive()

bool Cogs::Core::TaskQueue::isActive ( const TaskId & taskId )

inline

Definition at line 485 of file TaskManager.cpp.

◆ updateState()

void Cogs::Core::TaskQueue::updateState ( Context * context )

inline

Definition at line 554 of file TaskManager.cpp.

◆ wait()

void Cogs::Core::TaskQueue::wait ( const TaskId & taskId )

inline

Wait on the task given by taskId.

If the task has already been completed, returns immediately.

Parameters

taskId TaskId of the task to wait for.

Definition at line 497 of file TaskManager.cpp.

References Cogs::Core::Task::active, Cogs::Core::Task::generation, Cogs::Core::TaskId::generation, getTask(), Cogs::Core::TaskId::queueId, and yield().

Referenced by destroy().

◆ waitAll()

void Cogs::Core::TaskQueue::waitAll ( )

inline

Wait for all enqueued tasks to finish.

If any new tasks are added to the queue during this wait, those will also be waited for.

Definition at line 524 of file TaskManager.cpp.

References active, and yield().

◆ workOnTask()

void Cogs::Core::TaskQueue::workOnTask ( Task * task )

inline

Perform work on the given task.

If it is not possible to work on the given task, the worker will yield its resources to other tasks in the queue until the task becomes available.

When done working on the task, finishTask() will be called.

Parameters

task	Pointer to the task to work on.

Definition at line 391 of file TaskManager.cpp.

References canExecute(), finishTask(), Cogs::Core::Task::kernel, and yield().

Referenced by Cogs::Core::TaskWorker::operator()(), and yield().

◆ yield()

void Cogs::Core::TaskQueue::yield ( )

inline

Yield the currently executing thread to perform work on other available tasks or simply give back execution resources to the OS.

Definition at line 420 of file TaskManager.cpp.

References getAvailableTask(), and workOnTask().

Referenced by wait(), waitAll(), and workOnTask().

Member Data Documentation

◆ active

Atomic<int> Cogs::Core::TaskQueue::active {0}

private

Number of currently active tasks.

Definition at line 605 of file TaskManager.cpp.

Referenced by createTask(), destroyTask(), and waitAll().

◆ done

bool Cogs::Core::TaskQueue::done = false

private

If the queue is done and should stop executing tasks.

Definition at line 608 of file TaskManager.cpp.

Referenced by getNextTask(), and ~TaskQueue().

◆ generation

Atomic<uint16_t> Cogs::Core::TaskQueue::generation = 0

private

Generation counter used to track task lifetime.

Definition at line 611 of file TaskManager.cpp.

Referenced by createTask(), and destroyTask().

◆ id

TaskQueueId Cogs::Core::TaskQueue::id {0}

private

Id of the task queue.

Definition at line 626 of file TaskManager.cpp.

◆ lastFrame

uint32_t Cogs::Core::TaskQueue::lastFrame = 0

private

Definition at line 585 of file TaskManager.cpp.

◆ name

std::string Cogs::Core::TaskQueue::name

private

Name of the queue used for debugging.

Definition at line 602 of file TaskManager.cpp.

Referenced by initializeWorkers().

◆ poolMutex

Mutex Cogs::Core::TaskQueue::poolMutex

private

TaskPool mutex.

Definition at line 617 of file TaskManager.cpp.

Referenced by createTask(), destroyTask(), and getTask().

◆ queueState

QueueState Cogs::Core::TaskQueue::queueState {}

private

Definition at line 587 of file TaskManager.cpp.

◆ taskMutex

Mutex Cogs::Core::TaskQueue::taskMutex

private

Task queue mutex.

Definition at line 620 of file TaskManager.cpp.

Referenced by enqueueTask(), getAvailableTask(), getNextTask(), and ~TaskQueue().

◆ taskPool

TaskPool Cogs::Core::TaskQueue::taskPool

private

Task pool holding Task instances.s.

Definition at line 599 of file TaskManager.cpp.

Referenced by createTask(), destroyTask(), and getTask().

◆ taskQueue

std::queue<Task *> Cogs::Core::TaskQueue::taskQueue

private

Currently queued tasks, ready for execution by a TaskWorker.

Definition at line 614 of file TaskManager.cpp.

Referenced by enqueueTask(), getAvailableTask(), and getNextTask().

◆ taskVariable

std::condition_variable Cogs::Core::TaskQueue::taskVariable

private

Condition variable used to signal tasks available for execution.

Definition at line 623 of file TaskManager.cpp.

Referenced by enqueueTask(), getNextTask(), and ~TaskQueue().

◆ threads

std::vector<Thread> Cogs::Core::TaskQueue::threads

private

Array of threads used to execute TaskWorker instances.

Definition at line 629 of file TaskManager.cpp.

Referenced by enqueue(), enqueueTask(), initializeWorkers(), and ~TaskQueue().

◆ timer

Timer Cogs::Core::TaskQueue::timer = Timer::startNew()

private

Definition at line 584 of file TaskManager.cpp.

◆ workerStateData

std::unique_ptr<std::vector<QueueWorkerStateData> > Cogs::Core::TaskQueue::workerStateData

private

Tracks worker thread kernel launches continuosly.

Definition at line 593 of file TaskManager.cpp.

Referenced by initializeWorkers().

◆ workerStates

std::vector<QueueWorkerState> Cogs::Core::TaskQueue::workerStates

private

Aggregated worker state data.

Definition at line 590 of file TaskManager.cpp.

Referenced by initializeWorkers().

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

Source/Services/TaskManager.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TaskQueue()

◆ ~TaskQueue()

Member Function Documentation

◆ canExecute()

◆ create() [1/2]

◆ create() [2/2]

◆ createGroup()

◆ createTask()

◆ destroy()

◆ destroyTask()

◆ enqueue() [1/3]

◆ enqueue() [2/3]

◆ enqueue() [3/3]

◆ enqueueTask()

◆ finishTask()

◆ getAvailableTask()

◆ getConcurrency()

◆ getId()

◆ getName()

◆ getNextTask()

◆ getQueueState()

◆ getTask()

◆ initializeWorkers()

◆ isActive()

◆ updateState()

◆ wait()

◆ waitAll()

◆ workOnTask()

◆ yield()

Member Data Documentation

◆ active

◆ done

◆ generation

◆ id

◆ lastFrame

◆ name

◆ poolMutex

◆ queueState

◆ taskMutex

◆ taskPool

◆ taskQueue

◆ taskVariable

◆ threads

◆ timer

◆ workerStateData

◆ workerStates