MultiphaseTask

Data Structures
struct	MultiphaseTask
	Multiphase task with internal state machine for sequential execution phases. More...

Macros
#define	mptaskAddPhases(self, parr)   mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), false)
#define	mptaskAddFailPhases(self, parr)   mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), true)
#define	mptask_addPhases(self, num, parr, fail)   MultiphaseTask__addPhases(MultiphaseTask(self), num, parr, fail)
#define	mptaskRequireTask(self, dep, failok)   ComplexTask_requireTask(ComplexTask(self), Task(dep), failok)
#define	mptaskRequireTaskTimeout(self, dep, failok, timeout)   ComplexTask_requireTaskTimeout(ComplexTask(self), Task(dep), failok, timeout)
#define	mptaskRequireResource(self, res)   ComplexTask_requireResource(ComplexTask(self), TaskResource(res))
#define	mptaskRequireResourceTimeout(self, res, timeout)   ComplexTask_requireResourceTimeout(ComplexTask(self), TaskResource(res), timeout)
#define	mptaskRequireGate(self, gate)   ComplexTask_requireGate(ComplexTask(self), TRGate(gate))
#define	mptaskRequireGateTimeout(self, gate, timeout)   ComplexTask_requireGateTimeout(ComplexTask(self), TRGate(gate), timeout)
#define	mptaskRequire(self, req)   ComplexTask_require(ComplexTask(self), TaskRequires(req))
#define	mptaskAdvance(self)   ComplexTask_advance(ComplexTask(self))
#define	mptaskCheckRequires(self, updateProgress, expires)   ComplexTask_checkRequires(ComplexTask(self), updateProgress, expires)
#define	mptaskCancelRequires(self)   ComplexTask_cancelRequires(ComplexTask(self))
#define	mptaskAcquireRequires(self, acquired)   ComplexTask_acquireRequires(ComplexTask(self), acquired)
#define	mptaskReleaseRequires(self, resources)   ComplexTask_releaseRequires(ComplexTask(self), resources)
#define	mptaskRunCancelled(self, tq, worker)   (self)->_->runCancelled(MultiphaseTask(self), TaskQueue(tq), TQWorker(worker))
#define	mptaskWait(self, timeout)   (self)->_->wait(MultiphaseTask(self), timeout)
#define	mptaskFinish(self, result, tcon)   (self)->_->finish(MultiphaseTask(self), result, tcon)

Typedefs
typedef struct MultiphaseTask	MultiphaseTask
	Multiphase task with internal state machine for sequential execution phases.
typedef uint32(*	MPTPhaseFunc) (void *self, TaskQueue *tq, TQWorker *worker, TaskControl *tcon)

Enumerations
enum	MultiphaseTaskFlagsEnum { MPTASK_Greedy = 0x10 }
	Flags controlling MultiphaseTask behavior. More...

Detailed Description

MultiphaseTask (MPTask) extends ComplexTask for operations that proceed through multiple distinct phases. Instead of implementing a single run() method, you add phase functions that execute sequentially based on return values.

Key features:

• Phase functions are called in order from an array
• Each phase returns a result that determines what happens next
• Separate fail phases can be added for error handling
• Can be greedy (execute all phases without yielding) or cooperative (yield between phases)

Common workflow:

1. Add normal phases with mptaskAddPhases()
2. Optionally add fail phases with mptaskAddFailPhases()
3. Override finish() if you need custom cleanup or want to change the final result

Example:

static MPTPhaseFunc myPhases[] = {
    (MPTPhaseFunc)phase1,
    (MPTPhaseFunc)phase2,
    (MPTPhaseFunc)phase3,
};
 
static MPTPhaseFunc myFailPhases[] = {
    (MPTPhaseFunc)cleanup,
};
 
void mytaskInit(MyTask *self) {
    mptaskAddPhases(self, myPhases);
    mptaskAddFailPhases(self, myFailPhases);
}

Macro Definition Documentation

mptask_addPhases

#define mptask_addPhases	(		self,
			num,
			parr,
			fail
	)		MultiphaseTask__addPhases(MultiphaseTask(self), num, parr, fail)

void mptask_addPhases(MultiphaseTask* self, int32 num, MPTPhaseFunc parr[], bool fail);

Internal method to add phases from array. Use mptaskAddPhases() or mptaskAddFailPhases() macros instead.

Parameters

num	Number of phases in array
parr	Array of phase functions
fail	If true, these are fail phases

Definition at line 162 of file mptask.h.

mptaskAcquireRequires

#define mptaskAcquireRequires	(		self,
			acquired
	)		ComplexTask_acquireRequires(ComplexTask(self), acquired)

bool mptaskAcquireRequires(MultiphaseTask* self, sa_TaskRequires* acquired);

Try to acquire required resources.

Parameters

acquired

[out] List of successfully acquired resources

Returns

true if all resources were acquired

Definition at line 235 of file mptask.h.

mptaskAddFailPhases

#define mptaskAddFailPhases	(		self,
			parr
	)		mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), true)

mptaskAddFailPhases(MultiphaseTask* self, MPTPhaseFunc parr[])

Adds failure handling phases from a static array. These phases only run if a normal phase returns TASK_Result_Failure.

Definition at line 88 of file mptask.h.

mptaskAddPhases

#define mptaskAddPhases	(		self,
			parr
	)		mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), false)

mptaskAddPhases(MultiphaseTask* self, MPTPhaseFunc parr[])

Adds normal execution phases from a static array. The array size is automatically calculated.

Definition at line 83 of file mptask.h.

mptaskAdvance

#define mptaskAdvance

(

self

)

ComplexTask_advance(ComplexTask(self))

bool mptaskAdvance(MultiphaseTask* self);

Advance a deferred task to run as soon as possible.

Returns

true if task was advanced

Definition at line 215 of file mptask.h.

mptaskCancelRequires

#define mptaskCancelRequires

(

self

)

ComplexTask_cancelRequires(ComplexTask(self))

void mptaskCancelRequires(MultiphaseTask* self);

Cascade cancellation to dependencies if TASK_Cancel_Cascade is set.

Definition at line 228 of file mptask.h.

mptaskCheckRequires

#define mptaskCheckRequires	(		self,
			updateProgress,
			expires
	)		ComplexTask_checkRequires(ComplexTask(self), updateProgress, expires)

uint32 mptaskCheckRequires(MultiphaseTask* self, bool updateProgress, int64* expires);

Check if all requirements are satisfied.

Parameters

updateProgress	If true, update lastprogress timestamp
expires	[out] Earliest expiration time of any requirement

Returns

Requirement state (TASK_Requires_Wait, TASK_Requires_Ok, etc.)

Definition at line 223 of file mptask.h.

mptaskFinish

#define mptaskFinish	(		self,
			result,
			tcon
	)		(self)->_->finish(MultiphaseTask(self), result, tcon)

uint32 mptaskFinish(MultiphaseTask* self, uint32 result, TaskControl* tcon);

Called after all phases complete. Can be overridden to perform additional cleanup or change the final result.

Parameters

result	Result code from the last phase
tcon	Task control structure

Returns

Final result code for the task

Definition at line 276 of file mptask.h.

mptaskReleaseRequires

#define mptaskReleaseRequires	(		self,
			resources
	)		ComplexTask_releaseRequires(ComplexTask(self), resources)

bool mptaskReleaseRequires(MultiphaseTask* self, sa_TaskRequires resources);

Release previously acquired resources.

Parameters

resources

List of resources to release

Returns

true if resources were released

Definition at line 242 of file mptask.h.

mptaskRequire

#define mptaskRequire	(		self,
			req
	)		ComplexTask_require(ComplexTask(self), TaskRequires(req))

void mptaskRequire(MultiphaseTask* self, TaskRequires* req);

Add a generic requirement.

Parameters

req	Custom requirement object

Definition at line 209 of file mptask.h.

mptaskRequireGate

#define mptaskRequireGate	(		self,
			gate
	)		ComplexTask_requireGate(ComplexTask(self), TRGate(gate))

void mptaskRequireGate(MultiphaseTask* self, TRGate* gate);

Add a gate requirement.

Parameters

gate	Gate that must be opened before task runs

Definition at line 196 of file mptask.h.

mptaskRequireGateTimeout

#define mptaskRequireGateTimeout	(		self,
			gate,
			timeout
	)		ComplexTask_requireGateTimeout(ComplexTask(self), TRGate(gate), timeout)

void mptaskRequireGateTimeout(MultiphaseTask* self, TRGate* gate, int64 timeout);

Add a gate requirement with timeout.

Parameters

gate	Gate to wait for
timeout	Maximum time to wait for gate

Definition at line 203 of file mptask.h.

mptaskRequireResource

#define mptaskRequireResource	(		self,
			res
	)		ComplexTask_requireResource(ComplexTask(self), TaskResource(res))

void mptaskRequireResource(MultiphaseTask* self, TaskResource* res);

Add a resource requirement.

Parameters

res	Resource to acquire exclusively

Definition at line 183 of file mptask.h.

mptaskRequireResourceTimeout

#define mptaskRequireResourceTimeout	(		self,
			res,
			timeout
	)		ComplexTask_requireResourceTimeout(ComplexTask(self), TaskResource(res), timeout)

void mptaskRequireResourceTimeout(MultiphaseTask* self, TaskResource* res, int64 timeout);

Add a resource requirement with timeout.

Parameters

res	Resource to acquire
timeout	Maximum time to wait for resource

Definition at line 190 of file mptask.h.

mptaskRequireTask

#define mptaskRequireTask	(		self,
			dep,
			failok
	)		ComplexTask_requireTask(ComplexTask(self), Task(dep), failok)

void mptaskRequireTask(MultiphaseTask* self, Task* dep, bool failok);

Add a task dependency.

Parameters

dep	Task to depend on
failok	If true, don't fail if dep fails (soft dependency)

Definition at line 169 of file mptask.h.

mptaskRequireTaskTimeout

#define mptaskRequireTaskTimeout	(		self,
			dep,
			failok,
			timeout
	)		ComplexTask_requireTaskTimeout(ComplexTask(self), Task(dep), failok, timeout)

void mptaskRequireTaskTimeout(MultiphaseTask* self, Task* dep, bool failok, int64 timeout);

Add a task dependency with timeout.

Parameters

dep	Task to depend on
failok	If true, don't fail if dep fails
timeout	Maximum time to wait for dep

Definition at line 177 of file mptask.h.

mptaskRunCancelled

#define mptaskRunCancelled	(		self,
			tq,
			worker
	)		(self)->_->runCancelled(MultiphaseTask(self), TaskQueue(tq), TQWorker(worker))

void mptaskRunCancelled(MultiphaseTask* self, TaskQueue* tq, TQWorker* worker);

Called when task is cancelled before it can run.

Parameters

tq	Task queue the task was on
worker	Worker that picked up the cancelled task

Definition at line 254 of file mptask.h.

mptaskWait

#define mptaskWait	(		self,
			timeout
	)		(self)->_->wait(MultiphaseTask(self), timeout)

bool mptaskWait(MultiphaseTask* self, int64 timeout);

Wait for this task to complete.

Parameters

timeout

Maximum time to wait, or 0 to wait indefinitely

Returns

true if task completed within timeout

Definition at line 264 of file mptask.h.

Typedef Documentation

MPTPhaseFunc

typedef uint32(* MPTPhaseFunc) (void *self, TaskQueue *tq, TQWorker *worker, TaskControl *tcon)

Phase function signature for multiphase tasks.

Parameters

self	Pointer to the MultiphaseTask (cast to your derived type)
tq	Task queue the phase is running on
worker	Worker thread executing this phase
tcon	Task control structure for output parameters

Returns

Task result code (TASK_Result_Success, TASK_Result_Failure, etc.)

Definition at line 77 of file mptask.h.

Enumeration Type Documentation

MultiphaseTaskFlagsEnum

enum MultiphaseTaskFlagsEnum

Flags controlling MultiphaseTask behavior.

Enumerator
MPTASK_Greedy	Execute all phases immediately without yielding to other tasks.

Definition at line 68 of file mptask.h.