plTask Class Reference

Base class for custom tasks. More...

#include <Task.h>

Inheritance diagram for plTask:

Public Member Functions
void	ConfigureTask (const char *szTaskName, plTaskNesting nestingMode, plOnTaskFinishedCallback callback=plOnTaskFinishedCallback())
	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 (plUInt32 uiMultiplicity)
	Changes the multiplicity of this task.
plUInt32	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 plRefCounted
virtual	~plRefCounted ()=default
	Adds a virtual destructor.
Public Member Functions inherited from plRefCountingImpl
	plRefCountingImpl ()=default
	Constructor.
	plRefCountingImpl (const plRefCountingImpl &rhs)
void	operator= (const plRefCountingImpl &rhs)
plInt32	AddRef () const
	Increments the reference counter. Returns the new reference count.
plInt32	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.
plInt32	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 (plUInt32 uiInvocation) const
	Override this to implement the task's supposed functionality.

Friends
class	plTaskSystem

Detailed Description

Base class for custom tasks.

Member Function Documentation

ConfigureTask()

void plTask::ConfigureTask	(	const char *	szTaskName,
		plTaskNesting	nestingMode,
		plOnTaskFinishedCallback	callback = plOnTaskFinishedCallback() )

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

szTaskName	Will be displayed in profiling tools and is useful for debugging.
nestingMode	See plTaskNesting
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 plTask::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 plTaskSystem.

Reimplemented in ArrayPtrTask< ElemType >, plAfterSaveDocumentTask, plBakingInternal::PlaceProbesTask, plBakingInternal::SkyVisibilityTask, plDelegateTask< T >, plDelegateTask< void >, plNavMeshSectorGenerationTask, plParticleEffectUpdateTask, plProcGenInternal::FindPlacementTilesTask, plProcGenInternal::PlacementTask, plProcGenInternal::PreparePlacementTask, plProcGenInternal::VertexColorTask, plResourceManagerWorkerDataLoad, plResourceManagerWorkerUpdateContent, plSaveDocumentTask, and plUpdateTask.

ExecuteWithMultiplicity()

virtual void plTask::ExecuteWithMultiplicity ( plUInt32 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 plTaskSystem, 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()

plUInt32 plTask::GetMultiplicity ( ) const

inline

See also

SetMultiplicity

IsTaskFinished()

bool plTask::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 plTaskGroupID of the task's group. That one can be used to query whether the group has finished, even minutes later.

SetMultiplicity()

void plTask::SetMultiplicity

(

plUInt32

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 plTaskSystem, 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:

• Code/Engine/Foundation/Threading/Implementation/Task.h
• Code/Engine/Foundation/Threading/Implementation/Task.cpp