mptask.cxh

/// @brief Multiphase task with internal state machine
///
/// @defgroup mptask MultiphaseTask
/// @ingroup tq_task
/// @{
///
/// 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:**
/// @code
/// static MPTPhaseFunc myPhases[] = {
///     (MPTPhaseFunc)phase1,
///     (MPTPhaseFunc)phase2,
///     (MPTPhaseFunc)phase3,
/// };
///
/// static MPTPhaseFunc myFailPhases[] = {
///     (MPTPhaseFunc)cleanup,
/// };
///
/// void mytaskInit(MyTask *self) {
///     mptaskAddPhases(self, myPhases);
///     mptaskAddFailPhases(self, myFailPhases);
/// }
/// @endcode
#include "complextask.cxh"
 
/// Flags controlling MultiphaseTask behavior
enum MultiphaseTaskFlagsEnum {
    MPTASK_Greedy = 0x10        ///< Execute all phases immediately without yielding to other tasks
};
 
/// Phase function signature for multiphase tasks.
/// @param self Pointer to the MultiphaseTask (cast to your derived type)
/// @param tq Task queue the phase is running on
/// @param worker Worker thread executing this phase
/// @param tcon Task control structure for output parameters
/// @return Task result code (TASK_Result_Success, TASK_Result_Failure, etc.)
typedef uint32 (*MPTPhaseFunc)(void *self, TaskQueue* tq, TQWorker* worker, TaskControl *tcon);
saDeclare(MPTPhaseFunc);
 
/// mptaskAddPhases(MultiphaseTask* self, MPTPhaseFunc parr[])
///
/// Adds normal execution phases from a static array.
/// The array size is automatically calculated.
#define mptaskAddPhases(self, parr) mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), false)
 
/// 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.
#define mptaskAddFailPhases(self, parr) mptask_addPhases(self, sizeof(parr) / sizeof((parr)[0]), (parr), true)
 
/// Multiphase task with internal state machine for sequential execution phases.
[methodprefix mptask] abstract class MultiphaseTask extends ComplexTask {
    [noinit] sarray:MPTPhaseFunc phases;       ///< Normal execution phases
    [noinit] sarray:MPTPhaseFunc failphases;   ///< Failure handling phases
    uint32 _phase;                              ///< Current phase index
    bool _fail;                                 ///< True if currently executing fail phases
 
    /// Called after all phases complete.
    /// Can be overridden to perform additional cleanup or change the final result.
    /// @param result Result code from the last phase
    /// @param tcon Task control structure
    /// @return Final result code for the task
    uint32 finish(uint32 result, TaskControl *tcon);
 
    /// Internal method to add phases from array.
    /// Use mptaskAddPhases() or mptaskAddFailPhases() macros instead.
    /// @param num Number of phases in array
    /// @param parr Array of phase functions
    /// @param fail If true, these are fail phases
    unbound void _addPhases(int32 num, MPTPhaseFunc parr[], bool fail);
 
    override run;
    init();
}
/// @}