Open 3D Engine AzCore API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AZ::Job Class Referenceabstract

#include <Job.h>

Inherited by AZ::Internal::JobNotify, AZ::Internal::ParallelForChunkJob< Function, Partition >, AZ::Internal::ParallelForEachForwardFinishJobChunkHelper< ForwardIterator, Function, Partition >, AZ::JobCompletion, AZ::JobCompletionSpin, AZ::JobEmpty, AZ::JobFunction< Function >, and AZ::MultipleDependentJob.

Public Types

enum  State {
  STATE_SETUP , STATE_STARTED , STATE_PENDING , STATE_PROCESSING ,
  STATE_SUSPENDED
}
 

Public Member Functions

 Job (bool isAutoDelete, JobContext *context, bool isCompletion=false, AZ::s8 priority=0)
 
void Start ()
 
virtual void Reset (bool isClearDependent)
 
void SetDependent (Job *dependent)
 
void SetDependentStarted (Job *dependent)
 
void SetContinuation (Job *continuationJob)
 
void StartAsChild (Job *childJob)
 
void WaitForChildren ()
 
bool IsCancelled () const
 
bool IsAutoDelete () const
 
bool IsCompletion () const
 
void StartAndAssistUntilComplete ()
 
void StartAndWaitForCompletion ()
 
JobContextGetContext () const
 
JobGetDependent () const
 
unsigned int GetDependentCount () const
 
void IncrementDependentCount ()
 
void DecrementDependentCount ()
 
AZ::s8 GetPriority () const
 

Protected Member Functions

virtual void Process ()=0
 Override to implement your processing.
 
void StoreDependent (Job *job)
 
void SetDependentChild (Job *dependent)
 
void IncrementDependentCountAndSetChildFlag ()
 
void SetDependentCountAndFlags (unsigned int countAndFlags)
 
unsigned int GetDependentCountAndFlags () const
 

Protected Attributes

JobContext *volatile m_context
 
AZStd::atomic< unsigned int > m_dependentCountAndFlags
 
AZStd::atomic< Job * > m_dependent
 
int m_state
 

Detailed Description

Job class, representing a small unit of processing which can be parallelized with other jobs. This is the generic class for jobs, you will need to inherit from it and implement the Process function. In addition you can use a provided templates for a generic function JobFunction an EmptyJob (used for tracking) or JobCompletion/JobCompletionSpin used to wait for all dependent jobs to finish. Jobs by default will auto-delete when they are complete, which simplifies typical fork-join usage, and is not inefficient since Jobs have a custom pool allocator.

Dependency notes: Each job has at most one dependent job, which will be notified when this job completes. This is not as limiting as it may seem at first, since jobs can fork additional jobs from their Process function, effectively starting dependent jobs. Also jobs can manipulate the dependent count directly, allowing derived jobs to manage their dependents directly. See MultipleDependentJob for an example of this.

Constructor & Destructor Documentation

◆ Job()

AZ::Job::Job ( bool  isAutoDelete,
JobContext context,
bool  isCompletion = false,
AZ::s8  priority = 0 
)

If a JobContext is not specified, then the currently processing job's context will be used, or the global context from JobContext::SetGlobalContext will be used if this is a top-level job. isAutoDelete if true will call delete on the job after it's complete. isCompletion will allow the job to run when the dependent count is zero without being scheduled. priority is used to sort jobs such that higher priority jobs are run before lower priority ones. The valid range is -128 (lowest priority) to 127 (highest priority), the default is 0, and jobs with equal priority values will be run in the same order as added to the queue.

Member Function Documentation

◆ GetContext()

JobContext * AZ::Job::GetContext ( ) const
inline

Gets the context to which this job belongs.

◆ GetDependent()

Job * AZ::Job::GetDependent ( ) const

Gets the dependent job, the dependent job will not start until this job has completed.

◆ GetDependentCount()

unsigned int AZ::Job::GetDependentCount ( ) const

Dependency counter functions, these should not usually be used, unless you know what you're doing.

◆ IsAutoDelete()

bool AZ::Job::IsAutoDelete ( ) const

Checks if this job will automatically be deleted when it has finished processing, this was specified when job was created.

◆ IsCancelled()

bool AZ::Job::IsCancelled ( ) const

Checks if this job has been canceled. You can poll this during processing if you like, to return early.

◆ Process()

virtual void AZ::Job::Process ( )
protectedpure virtual

Override to implement your processing.

Implemented in AZ::JobCompletion, AZ::JobCompletionSpin, AZ::JobEmpty, AZ::MultipleDependentJob, and AZ::JobFunction< Function >.

◆ Reset()

virtual void AZ::Job::Reset ( bool  isClearDependent)
virtual

Resets a non-auto-deleting job so it can be used again. If the dependent is not cleared, then it should be already in the reset state, in order to increment the dependent count.

Reimplemented in AZ::JobCompletion, AZ::JobCompletionSpin, and AZ::MultipleDependentJob.

◆ SetContinuation()

void AZ::Job::SetContinuation ( Job continuationJob)

A continuation job is a job which will follow this job, and continues its work, in the sense that this jobs dependent will not run until the continuation job is also complete. It can only be called while this job is currently processing, otherwise a regular dependent should be used.

A common usage for continuation jobs is when forking new jobs from a processing job. The forked jobs (or the join job if present) will be set as continuations of the current job, which ensures that the dependent set by the caller of this job will not run until the forked jobs have completed.

The continuation is implemented by setting the dependent of the continuation job to be the dependent of this job, i.e. this function is equivalent to calling: continuationJob->SetDependentStarted(this->GetDependent()), with some extra asserts for safety.

◆ SetDependent()

void AZ::Job::SetDependent ( Job dependent)

Sets the dependent job. The dependent job will not not be allowed to run until this job is complete. Both jobs should be in the un-started state when calling this function.

◆ SetDependentStarted()

void AZ::Job::SetDependentStarted ( Job dependent)

Alternative version of SetDependent, for experts only. Almost identical except it does not require the dependent to be in the un-started state. Use the regular SetDependent wherever possible, this function is tricky to use correctly, and not all errors can be caught by assertions. It is the users responsibility to ensure that the dependent has not already been run, e.g. if this is called from a job on which the dependent job is waiting.

◆ Start()

void AZ::Job::Start ( )

Allows the job to start executing. Auto-delete jobs should not be accessed after calling this function.

◆ StartAndAssistUntilComplete()

void AZ::Job::StartAndAssistUntilComplete ( )

Starts this job, and then uses this thread to assist with job processing until it is complete. This can only be called on a non-worker thread. Please think twice when using this function, it is not guaranteed to be an automatic performance boost, as many factors come into play.

◆ StartAndWaitForCompletion()

void AZ::Job::StartAndWaitForCompletion ( )

If we are in a worker thread this will start the job as a child job and wait for children to complete. If we are in a non-worker this will use a StartAndAssistUntilComplete to block until the job completes. The job must not have a dependent when this function is called.

◆ StartAsChild()

void AZ::Job::StartAsChild ( Job childJob)

This starts the specified job and adds it as a child to this job. This job must be currently processing when this function is called. Before processing is finished, this job must call WaitForChildren to block until all child jobs are complete.

◆ WaitForChildren()

void AZ::Job::WaitForChildren ( )

Suspends processing of this job until all children are complete. The thread currently running the job will resume running other jobs until the children are complete.


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