Astra.Job Class Reference

A job is a unit of work that you need done you can provide data to it, talk to it, get progress get ids, depend on other jobs, have sub jobs, execute on main thread, etc More...

Inheritance diagram for Astra.Job:

Classes
class	Exception

Public Types
enum	State { PENDING = 0 , AVAILABLE = 1 , RUNNING = 2 , DONE = 3 }
	Run state of a job More...
enum	JobEventStage {   Unknown = 0 , DoneSide = 1 , DoneMain = 2 , Done = 3 ,   Success = 4 , Failed = 5 , Finally = 6 , PostFinally = 7 ,   Finished = 8 }
	Job tracking stage

Public Member Functions
	Job ()
	Base constructor for a job
bool	IsDone ()
	Informs you if the status of a job is complete (succeeded or failed) More...
bool	IsSuccessful ()
	Informs you if the job is finished and succeeded in running. More...
bool	IsFailed ()
	Informs you if the job is finished and failed while running. More...
virtual void	Freeze ()
	Tell the job queue not to run this until it's ready Moves state from AVAILABLE to PENDING, does nothing if not in AVAILABLE state This is useful if you don't know the preconditions for a job to begin until another async operation It is very important to Thaw() a frozen job or your job will never run from the queue More...
virtual void	Thaw (bool runImmediate=false)
	Tell the job queue that this job is ready to be run Moves state from PENDING to AVAILABLE More...
virtual void	CompleteWithSuccess ()
	If you have a custom function, you can mark a job complete with this
virtual void	CompleteWithFailure ()
	If you have a custom function, you can mark the job as a failure with this
virtual void	Abort ()
	Stop this job and abort any children of this job
virtual void	AbortDependencies ()
	Signal that any job that this job depended on should be aborted NOTE: this is handled in the queue
virtual void	DependsOn (Job subJob)
	Only fire this job's function when these job(s) are completed More...
virtual void	DependsOn (List< Job > subJobs)
	Only fire this job's function when these job(s) are completed More...
virtual void	CompleteAfter (List< Job > jobs, bool abortOnFailure=true)
	Auto-Complete this job after the list of jobs passed in finishes (including callbacks) More...
virtual void	CompleteAfter (Job job)
	Autocomplete a job after this job is complete More...
virtual void	Run ()
	Starts executing the function waiting to run in the job More...
bool	IsYieldable ()
	Whether this function has been set up as a yieldable job More...
bool	WaitForCompletion (int timeout=-1)
	Block indefinitely or for specified timeout (in ms) More...
delegate void	JobDone (Job job)
delegate void	JobDoneMain (Job job)
delegate void	JobDoneSide (Job job)
delegate void	JobSuccess (Job job)
delegate void	JobFailed (Job job)
delegate void	JobAborted (Job job)
delegate void	JobFinally (Job job)
delegate void	JobPostFinally (Job job)
delegate void	JobProgressUpdate (Job job)
delegate void	JobPostEventsFired (Job job)
delegate void	JobStateChange (Job job, State previousState)
delegate void	JobStarted (Job job)
delegate void	JobDependencyChange (Job job, Job subJob)
delegate void	JobAbortDependencies (Job job)
delegate void	JobEnqueued (Job job)
delegate void	JobDelegate (Job job)
bool	Equals (Job x, Job y)
	Tells you if a job is equal to another job More...
int	GetHashCode (Job obj)
	Generates a hashcode that is faster then the builtin, useful for loookups. More...
WaitForJob	WaitUntilDone ()
	Used in a yieldable function/corountine where it will block continuation of the method until the job has finished (success or failure) More...
override string	ToString ()
	Converts the job to a debugging string, does not serialize the job. More...

Public Attributes
string	name
	Name of the job, which makes it easier to debug. Optional.
System.Diagnostics.Stopwatch	swWaitingTime = new System.Diagnostics.Stopwatch()
List< Job >	dependents = new List<Job>()
	A list of jobs that must be completed before this job can started
Func< Job, bool?>	function = null
	Function that is called as this Job is executed
Func< Job, IEnumerator >	functionAlt = null
	Yieldable function, called when this job is executed
MonoBehaviour	functionAltContext = null
	Owner of this Job, so that a yieldable function can be called
bool	functionNoOp = false
	Set this to true if you want the Run function to essentially do nothing and you're using something else to complete This means if you have a "function" defined it will NOT run NOTE: your job will not auto complete, you must handle that yourself such as with CompleteWithSuccess()

Static Public Attributes
const int	kNoParentJobId = -1

Protected Member Functions
bool	NeedsAndIsntMainThread (bool? requestedMainThread=null)
bool	NeedsAndIsntSideThread (bool? requestedMainThread=null)
delegate void	JobEventTrigger (Job job)

Protected Attributes
int	_id = -1
bool	_mainThread = false
float	_delay = 0
int	_stepsTotal = 0
int	_stepsCurrent = 0
System.Diagnostics.Stopwatch	swRunTime = new System.Diagnostics.Stopwatch()
System.Diagnostics.Stopwatch	swWholeTime = new System.Diagnostics.Stopwatch()
State	_state = State.AVAILABLE
ManualResetEvent	_complete = null
bool	_dependsOnAbortsOnFailure = true
JobEventStage	_currentEventStage = JobEventStage.Unknown

Static Protected Attributes
static Job	_alreadySuccessfulJob = null
static ApiJobNoResult	_alreadySuccessfulApiJob = null
static int	_globalId = 100

Properties
int	id [get]
	Id for the job
int	parentId [getset]
	Id for the job that is this job's parent
bool	mainThread [getset]
	Set to true if this job must run on the main thread (ie: it will access things like gameobjects)
float	delay [getset]
	If >0 delay the job from starting until X ms after being enqueued
float	progress [get]
	Returns the current job progress as a ratio from 0->1 where 0 is 0% complete, 0.5 is 50% complete, and 1.0 is 100% complete These are tracked by stepsCurrent and stepsTotal
int	stepsCurrent [getset]
	Number of steps currently taken for the Job, used to calculate progress
int	stepsTotal [getset]
	Total number of steps for the Job, used to calculate progress
bool	debug [getset]
	Sets whether debug information will be tracked by this job
bool?	wasAborted [getset]
	True if the job was aborted in any way (canceled due to exception, pulled out of queue, etc)
bool??	wasSuccess [getset]
	Whether the job was successful, a state of null means that the job status is unknown (likely in the queue or still running). NOTE: this property is legacy and you should instead use the IsDone, IsSuccessful, IsFailed calls instead
State??	state [getset]
	Whether the job is waiting, running, or done
bool	DoesFailedDependencyAbortParent [getset]
	Get or set whether this job fails if any of its dependencies fail
bool	IsDelayed [get]
	Returns false if there is no delay, or delay has been satisfied
bool	IsWaitingOn [get]
	If true, means we have WaitUntil jobs that still aren't ready
List< Job >	waitingOn [get]
	Job that this job is waiting on
JobPostEventsFired	OnPostEventsFired
JobDone	OnJobDone
	Fired after a job is completed regardless of it's state, this will fire before OnJobSuccess
JobDoneMain	OnJobDoneMain
	Fired when a job is completed regardless of state, this event is guaranteed to fire on the main thread regardless of the function thread the job was run on.
JobDoneSide	OnJobDoneSide
	Fired when a job is completed regardless of state, this event is guaranteed to fire on a side thread regardless of the function thread the job was run on.
JobSuccess	OnJobSuccess
	Fired only if the job is successful after it completes
JobFailed	OnJobFailed
	Fired only if the job fails after it completes
JobAborted	OnJobAborted
	fired if the job was aborted (exception, removed from queue, etc)
JobFinally	OnJobFinally
	Fired after done, success, and failure jobs. This is useful if you need to ensure other event callbacks are completed before tripping this one.
JobPostFinally	OnJobPostFinally
	Fired at the very end of a job Run after done, success, and failures have fired. This is typically used internally by things like the Astra.JobQueue.
JobProgressUpdate	OnJobProgress
	Fired periodically whenever we get an update on our progress of the job, NOTE: not all jobs will emit this event

Events
JobStarted	OnJobStart
JobStateChange	OnJobStateChange
JobDependencyChange	OnJobDependencyChange
JobEnqueued	OnJobEnqueued

Detailed Description

A job is a unit of work that you need done you can provide data to it, talk to it, get progress get ids, depend on other jobs, have sub jobs, execute on main thread, etc

Member Enumeration Documentation

State

enum Astra.Job.State

Run state of a job

Enumerator
PENDING	The job is not running and isn't available to run yet, Freezing and Thawing will move the job between PENDING and AVAILABLE
AVAILABLE	The job is available to run, but may be waiting on something (dependents for example)
RUNNING	The job is actually tripped and running (set by the Run() func)
DONE	The job is finished running and it either succeeded, failed, was aborted, etc you don't know, check _wasSuccess

Member Function Documentation

CompleteAfter() [1/2]

virtual void Astra.Job.CompleteAfter ( Job  job )

inlinevirtual

Autocomplete a job after this job is complete

Parameters

job	Job to wait for

See also

CompleteAfter

CompleteAfter() [2/2]

virtual void Astra.Job.CompleteAfter ( List< Job >  jobs, bool  abortOnFailure = true  )

inlinevirtual

Auto-Complete this job after the list of jobs passed in finishes (including callbacks)

This is similar to DependsOn, however DependsOn does not auto-complete a job unless function is null. This will autocomplete the job when all WaitUntil jobs are done This will prevent the current job starting to run until waiting on jobs are finished, in most cases you probably are already running the job though

Parameters

jobs	List of jobs that this job will be marked complete after being finished
abortOnFailure	True if this job should abort if there were failures in the waiting jobs. Otherwise it will be marked as a failure itself.

See also

DependsOn

DependsOn() [1/2]

virtual void Astra.Job.DependsOn ( Job  subJob )

inlinevirtual

Only fire this job's function when these job(s) are completed

<remakrs>Each call to this will append the sub job to this job, it is ok to call this multiple times.

Parameters

subJob

Job that this job will depend on

See also

DoesFailedDependencyAbortParent, CompleteAfter

DependsOn() [2/2]

virtual void Astra.Job.DependsOn ( List< Job >  subJobs )

inlinevirtual

Only fire this job's function when these job(s) are completed

Parameters

subJobs

List of jobs that this job will depend on

See also

DoesFailedDependencyAbortParent, CompleteAfter

Equals()

bool Astra.Job.Equals ( Job  x, Job  y  )

inline

Tells you if a job is equal to another job

Parameters

x	The first job to compare
y	The second job to compare

Returns

True if the jobs are the same, false otherwise

Freeze()

virtual void Astra.Job.Freeze ( )

inlinevirtual

Tell the job queue not to run this until it's ready Moves state from AVAILABLE to PENDING, does nothing if not in AVAILABLE state This is useful if you don't know the preconditions for a job to begin until another async operation It is very important to Thaw() a frozen job or your job will never run from the queue

<remarkes> you should avoid using this and instead use a normal chain of dependencies or waiting on instead as this makes running jobs finnicky and brittle, you may end up with a very difficult bug to track down due to a job not running </remakrs>

GetHashCode()

int Astra.Job.GetHashCode ( Job  obj )

inline

Generates a hashcode that is faster then the builtin, useful for loookups.

Parameters

obj	The job to get the hashcode from

Returns

An integer that is unique for each job

IsDone()

bool Astra.Job.IsDone ( )

inline

Informs you if the status of a job is complete (succeeded or failed)

Returns

True if the job is done (where state == State.Done), false otherwise

IsFailed()

bool Astra.Job.IsFailed ( )

inline

Informs you if the job is finished and failed while running.

Returns

True if the job is complete and a failure occurred (self or dependency)

IsSuccessful()

bool Astra.Job.IsSuccessful ( )

inline

Informs you if the job is finished and succeeded in running.

Returns

True if the job was successful and is complete

IsYieldable()

bool Astra.Job.IsYieldable ( )

inline

Whether this function has been set up as a yieldable job

See also

functionAlt

Run()

virtual void Astra.Job.Run ( )

inlinevirtual

Starts executing the function waiting to run in the job

Implements Astra.IJob.

Thaw()

virtual void Astra.Job.Thaw ( bool  runImmediate = false )

inlinevirtual

Tell the job queue that this job is ready to be run Moves state from PENDING to AVAILABLE

Parameters

runImmediate

If true, run the job right now, if false, let queue run it when ready

ToString()

override string Astra.Job.ToString ( )

inline

Converts the job to a debugging string, does not serialize the job.

Returns

A string useful for logging or printing info from

WaitForCompletion()

bool Astra.Job.WaitForCompletion ( int  timeout = -1 )

inline

Block indefinitely or for specified timeout (in ms)

NOTE: do NOT use this if you need main thread and you need to depend on another job that is also on main thread, instead just use the callback system, otherwise you will deadlock.TODO: in theory we can check for this during push and throw an exception

Parameters

timeout

Timeout time in milliseconds, -1 for no timeout

Returns

false if timeout occurred, true otherwise, CHECK job.wasSuccess or other state information

WaitUntilDone()

WaitForJob Astra.Job.WaitUntilDone ( )

inline

Used in a yieldable function/corountine where it will block continuation of the method until the job has finished (success or failure)

Returns

A yieldable class

Member Data Documentation

_alreadySuccessfulJob

Job Astra.Job._alreadySuccessfulJob = null

staticprotected

These are hardcoded jobs you can use to make your life easier if you need a pre-made job and you don't want it to clutter up the jobs, much like Vector3.Empty or similar

---

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

• Assets/Astra/JobSystem/Job.cs