resonance 1.0.1
Loading...
Searching...
No Matches
Task Class Referenceabstract

Cooperative unit of work that the run ring polls once per pass. More...

#include <task.h>

Inheritance diagram for Task:
Collaboration diagram for Task:

Classes

struct  Node
 One position in the run ring, allocated separately from the task it refers to. More...

Public Member Functions

 Task ()
 Task (const Task &other)
 Construct a task with its own fresh node.
virtual ~Task ()
 Unlink the task and release its node.
Task & operator= (const Task &other)
 Reset the task to kTaskStateIdle.
int Start (int bBlocking)
 Begin running the task.
int Suspend ()
 Unlink the task and retain its position.
int Reset ()
 Return the task to kTaskStateIdle so that it can be started again.
int Finish ()
 Retire the task.
int State () const
 Read the task's lifecycle position.
int InProgress () const
 Test whether the task has been started and has not yet finished.
float GetProgress ()
 Read how far the task has progressed.
HxStr GetStatus () const
 Read the task's display title.
int GetQuiet ()
 Test whether the task suppresses its progress report.
Public Member Functions inherited from Attachment
 Attachment ()
virtual ~Attachment ()
int Release ()
 Give back one reference and destroy the object once the last one is gone.
virtual void Destroy ()
 Destroy the object.

Static Public Member Functions

static int PollTasks ()
 Poll every running task once.
Static Public Member Functions inherited from Attachment
static void ReleaseIfSet (Attachment *pAttachment)
 Give back one reference to an object that may be null.

Protected Member Functions

virtual float Progress ()=0
 Report how far the task has progressed.
virtual HxStr Name () const =0
 Report the task's display title.
virtual int Quiet ()
 Report whether the task suppresses its progress report.
virtual int CheckStateChange (int nFrom, int nTo)
 Approve or refuse a lifecycle change.
virtual int Poll ()=0
 Perform one pass of the task's work.

Additional Inherited Members

Public Attributes inherited from Attachment
int mRefs

Detailed Description

Cooperative unit of work that the run ring polls once per pass.

Its RTTI descriptor is at 0x008f07d0. It derives virtually from Attachment. The virtual base places the Attachment subobject at the end of the most derived object, at +0x0c for a standalone Task, and the compiler-generated pointer to it at +0x00. Because the only base is virtual, the class also receives a vptr of its own, at +0x08, for the five virtuals it declares. The one declared member therefore occupies +0x04 and the class is 0x14 bytes.

The table at 0x00821150 addressed by that vptr runs GetTypeInfo then the five virtuals in declaration order, with no destructor slot. The inherited destructor takes slot 1 of the Attachment table at 0x00821188, each of whose entries adjusts this by -0x0c.

A task owns one heap-allocated Node, and the run ring links that node rather than the task itself. Start() has two forms. One links the node and returns, after which PollTasks() drives the task; the other runs the task to completion before returning. While a task is linked the ring owns one reference to it, taken in Start() and given back once the task is no longer in kTaskStateRunning.

MainLoop is the only class in the image that derives from Task. Every member below other than the constructors and the destructor is unreferenced, because each call site inlined its own copy.

Constructor & Destructor Documentation

◆ Task() [1/2]

Task::Task ( )
Ghidra address:
NTSC-U/C: 0x004b6270
Ghidra address:
PAL: 0x004f4580

◆ Task() [2/2]

Task::Task ( const Task & other)

Construct a task with its own fresh node.

The source task supplies nothing. The body is identical to the default constructor.

Parameters
otherThe task to copy. The binary reads nothing from it.
Ghidra address:
NTSC-U/C: 0x004b6708
Ghidra address:
PAL: 0x004f4a18

◆ ~Task()

virtual Task::~Task ( )
virtual

Unlink the task and release its node.

Destroying a task that is still running reports hx: destroying active task and then unlinks it.

Ghidra address:
NTSC-U/C: 0x004b6808
Ghidra address:
PAL: 0x004f4b18

Member Function Documentation

◆ operator=()

Task & Task::operator= ( const Task & other)

Reset the task to kTaskStateIdle.

Parameters
otherThe task to copy, which is compared against this one and otherwise unused.
Returns
This task.
Ghidra address:
NTSC-U/C: 0x004b6928
Ghidra address:
PAL: 0x004f4c38

◆ Start()

int Task::Start ( int bBlocking)

Begin running the task.

A blocking start polls the task to completion before returning and never links it into the ring. A non-blocking start links the node, takes one reference, and returns.

Parameters
bBlockingNon-zero to run the task to completion in this call.
Returns
Zero when the task has already finished or when CheckStateChange() refused.
Ghidra address:
NTSC-U/C: 0x004b6370
Ghidra address:
PAL: 0x004f4680

◆ Suspend()

int Task::Suspend ( )

Unlink the task and retain its position.

Returns
Zero when the task is not running and when CheckStateChange() refused.
Ghidra address:
NTSC-U/C: 0x004b6968
Ghidra address:
PAL: 0x004f4c78

◆ Reset()

int Task::Reset ( )

Return the task to kTaskStateIdle so that it can be started again.

Returns
Zero when CheckStateChange() refused.
Ghidra address:
NTSC-U/C: 0x004b6a28
Ghidra address:
PAL: 0x004f4d38

◆ Finish()

int Task::Finish ( )

Retire the task.

Returns
Zero when CheckStateChange() refused.
Ghidra address:
NTSC-U/C: 0x004b6ae8
Ghidra address:
PAL: 0x004f4df8

◆ State()

int Task::State ( ) const

Read the task's lifecycle position.

Returns
A TaskState.
Ghidra address:
NTSC-U/C: 0x004b6958
Ghidra address:
PAL: 0x004f4c68

◆ InProgress()

int Task::InProgress ( ) const

Test whether the task has been started and has not yet finished.

Returns
Non-zero while the state is kTaskStateRunning or kTaskStateSuspended.
Ghidra address:
NTSC-U/C: 0x004b65e8
Ghidra address:
PAL: 0x004f48f8

◆ GetProgress()

float Task::GetProgress ( )

Read how far the task has progressed.

Returns
The value the task reports.
Ghidra address:
NTSC-U/C: 0x004b6610
Ghidra address:
PAL: 0x004f4920

◆ GetStatus()

HxStr Task::GetStatus ( ) const

Read the task's display title.

Returns
The title the task reports.
Ghidra address:
NTSC-U/C: 0x004b6638
Ghidra address:
PAL: 0x004f4948

◆ GetQuiet()

int Task::GetQuiet ( )

Test whether the task suppresses its progress report.

Returns
Non-zero to suppress the report.
Ghidra address:
NTSC-U/C: 0x004b6670
Ghidra address:
PAL: 0x004f4980

◆ PollTasks()

int Task::PollTasks ( )
static

Poll every running task once.

One pass advances the ring by one position and polls the task the previous position referred to. A task that reports completion is retired and released. A task that reports more work to do has its progress reported unless it is quiet.

Returns
Non-zero while the ring still includes a task.
Ghidra address:
NTSC-U/C: 0x004b6490
Ghidra address:
PAL: 0x004f47a0

◆ Progress()

virtual float Task::Progress ( )
protectedpure virtual

Report how far the task has progressed.

The run ring discards the value.

Returns
A fraction of the work completed.

Implemented in MainLoop.

◆ Name()

virtual HxStr Task::Name ( ) const
protectedpure virtual

Report the task's display title.

Returns
The title.

Implemented in MainLoop.

◆ Quiet()

virtual int Task::Quiet ( )
protectedvirtual

Report whether the task suppresses its progress report.

Returns
Non-zero to suppress the report. The default is zero.
Ghidra address:
NTSC-U/C: 0x004b6bb0
Ghidra address:
PAL: 0x004f4ec0

◆ CheckStateChange()

virtual int Task::CheckStateChange ( int nFrom,
int nTo )
protectedvirtual

Approve or refuse a lifecycle change.

Every transition consults this before it is applied.

Parameters
nFromThe current TaskState.
nToThe requested TaskState.
Returns
Zero to refuse the change. The default approves every change.
Ghidra address:
NTSC-U/C: 0x004b6bb8
Ghidra address:
PAL: 0x004f4ec8

◆ Poll()

virtual int Task::Poll ( )
protectedpure virtual

Perform one pass of the task's work.

Returns
Non-zero while work remains.

Implemented in MainLoop.


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