Base class for custom tasks. More...

#include <Task.h>

Inheritance diagram for xiiTask:

Public Member Functions
void	ConfigureTask (xiiStringView sTaskName, xiiTaskNesting nestingMode, xiiOnTaskFinishedCallback callback=xiiOnTaskFinishedCallback())
	Sets the most important task properties. This has to be done before the task is added to a task group for the first time.

void	SetMultiplicity (xiiUInt32 uiMultiplicity)
	Changes the multiplicity of this task.

xiiUInt32	GetMultiplicity () const

bool	IsTaskFinished () const
	Returns whether the task has been finished. This includes being canceled.

bool	HasBeenCanceled () const
	Can be used inside an overridden 'Execute' function to terminate execution prematurely.

Public Member Functions inherited from xiiRefCounted
virtual	~xiiRefCounted ()=default
	Adds a virtual destructor.

Public Member Functions inherited from xiiRefCountingImpl
	xiiRefCountingImpl ()=default
	Constructor.

	xiiRefCountingImpl (const xiiRefCountingImpl &rhs)

void	operator= (const xiiRefCountingImpl &rhs)

xiiUInt32	AddRef () const
	Increments the reference counter. Returns the new reference count.

xiiUInt32	ReleaseRef () const
	Decrements the reference counter. Returns the new reference count.

bool	IsReferenced () const
	Returns true if the reference count is greater than 0, false otherwise.

xiiUInt32	GetRefCount () const
	Returns the current reference count.

Protected Member Functions
virtual void	Execute ()
	Override this to implement the task's supposed functionality.

virtual void	ExecuteWithMultiplicity (xiiUInt32 uiInvocation) const
	Override this to implement the task's supposed functionality.

Friends
class	xiiTaskSystem

Detailed Description

Base class for custom tasks.

Member Function Documentation

◆ ConfigureTask()

void xiiTask::ConfigureTask	(	xiiStringView	sTaskName,
		xiiTaskNesting	nestingMode,
		xiiOnTaskFinishedCallback	callback = xiiOnTaskFinishedCallback() )

Sets the most important task properties. This has to be done before the task is added to a task group for the first time.

Parameters

sTaskName	Will be displayed in profiling tools and is useful for debugging.
nestingMode	See xiiTaskNesting
Callback	A callback to execute when the task is finished (or canceled). The most common use case for this is to deallocate the task at that time.

◆ Execute()

virtual void xiiTask::Execute ( )

inlineprotectedvirtual

Override this to implement the task's supposed functionality.

This function is called for tasks that do not use multiplicity. They are executed a single time for each time they are added to the xiiTaskSystem.

Reimplemented in ArrayPtrTask< ElemType >, xiiAfterSaveDocumentTask, xiiDelegateTask< T >, xiiDelegateTask< void >, xiiDelegateTask< void >, xiiResourceManagerWorkerDataLoad, xiiResourceManagerWorkerUpdateContent, xiiSaveDocumentTask, and xiiUpdateTask.

◆ ExecuteWithMultiplicity()

virtual void xiiTask::ExecuteWithMultiplicity ( xiiUInt32 uiInvocation ) const

inlineprotectedvirtual

Override this to implement the task's supposed functionality.

This function is called for tasks that use multiplicity. A task that uses multiplicity is automatically run N times by the xiiTaskSystem, each time with an increasing invocation index. This allows to have a single task to handle something, but then decide dynamically how often to execute it, to subdivide the workload into multiple pieces. Since the same task is executed multiple times in parallel, tasks with multiplicity should not have any mutable state, which is why this function is const.

Reimplemented in ArrayPtrTask< ElemType >.

◆ GetMultiplicity()

xiiUInt32 xiiTask::GetMultiplicity ( ) const

inline

See also: SetMultiplicity

◆ IsTaskFinished()

bool xiiTask::IsTaskFinished ( ) const

inline

Returns whether the task has been finished. This includes being canceled.

Note: This function is only reliable when you KNOW that the task has not been reused. So that limits its usage to the time frame while the task is in use, and it should only be queried by code that actually manages when to reuse the task. If other code needs to be able to check whether a task is finished, you should give it the xiiTaskGroupID of the task's group. That one can be used to query whether the group has finished, even minutes later.

◆ SetMultiplicity()

void xiiTask::SetMultiplicity ( xiiUInt32 uiMultiplicity )

Changes the multiplicity of this task.

This has to be set before the task is scheduled, ie. before the task group that the task belongs to has all its dependencies fulfilled and has its tasks queued for execution. It is allowed to change the multiplicity after the task is added to the xiiTaskSystem, as long as the calling code guarantees to set this value in time.

A task that has a multiplicity of zero (the default) will have its Execute() function called exactly once. A task with a multiplicity of N will have its ExecuteWithMultiplicity() function called exactly N times, potentially in parallel on multiple threads. Since N can be dynamically decided each frame, one can dynamically scale the amount of parallelism according to the workload.

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

/home/runner/work/XII/XII/Source/Engine/Foundation/Threading/Implementation/Task.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Threading/Implementation/Task.cpp

Public Member Functions

Protected Member Functions

Friends