Shaft::baseproc

Shaft::baseproc implements a concurrent actor framework based on scheduling units called a "base procedure". BaseProcs can be asynchronously created by an application and later inserted into the system and modified via requests.

BaseProcMgr

Manages BaseProcs and BaseProc related sub-managers. Active and sleeping BaseProcs create a job graph spanning 4 "stages" with 8 "priorities" each, for 32 separate job graphs. The job graphs are processed one after the other, following the priorities from highest (0) to lowest (7) before advancing to the next stage. The jobs within each graph are processed concurrently with respect to their dependencies.

Lifecycle

BaseProcMgr has 5 main states it can move between by various api calls.

Idle

The system is at rest. Accessing BaseProcs through BaseProcLinks outside the system is legal.

Building

The system is building the job graph. Active BaseProcs will insert their jobs, and sleeping BaseProcs will instead insert their sleep job if they have one.

BaseProc Processing

The system is running the current job graph. Accessing BaseProcs through BaseProcLinks outside the system is illegal.

Removal Processing

The system is processing removal requests. Successfully removed BaseProcs are scheduled for asynchronous deletion.

Request Processing

The system is processing BaseProc requests. It may be illegal to access a BaseProc outside the system at this time.

BaseProc

Harbors up to 1 job for each stage and priority. As well as up to 1 sleep job. Is a member of the BaseProc tree. Has global meta-data for being referenced by BaseProcLinks. Can have dependency relations with other BaseProcs.

Lifecycle

A BaseProc has 12 states grouped into 4 "cycles"; initialization (3), live (4), removal (3), and finalization (2).

Initialization

This group of states is progressed linearly along the creation of a BaseProc.

Uninitialized

The default state on creation.

PendingInitialize

The BaseProc is in the state of being initialized.

Initialized

The BaseProc has been initialized. Next request processing a "PostInitialize" function will be called once per processing, if it fails the BaseProc may be deleted, or the system may try again under certain conditions. Trying again may not be intended.

Live

This group of states represents a BaseProc that is "live" in the system. The initial state after "PostInitialize" succeeds is PendingActive, from there a BaseProc can move between Active, Sleeping, or Paused.

PendingActive

The initial "Live" state of a BaseProc. RequestCancelSleep or RequestCancelPause can be used to attempt to activate the BaseProc.

Active

The quintessential "Live" state. All of the BaseProc's active jobs will be used in job graph building.

Sleeping

A heavyweight break in a BaseProc's processing. The BaseProc's sleep job will be used in job graph building. RequestCancelSleep will activate the BaseProc.

Paused

A lighter break in a BaseProc's processing. The BaseProc's sleep job will be used in job graph building. RequestCancelPause will unpause the BaseProc.

Removal

After a delete request is processed, a BaseProc is transitioned to the PendingRemoval state.

PendingRemoval

The BaseProc is removing itself from the application's subsystems. When the OnRemove callback succeeds the BaseProc immediately transitions to the Removal state.

Removal

The BaseProc removes it's BaseProcLink meta data, invalidating all BaseProcLinks to it, calls the OnStateRemoval callback, and then immediately transitions to the Removed state.

Removed

Next time there is space the BaseProc will be added to the asynchronous deletion queue and transitioned to the PendingFinalize state.

Finalization

This group of states to track a BaseProc's asynchronous finalization up to it's deletion.

PendingFinalization

The BaseProc will call it's PreFinalize callback, remove itself from the BaseProcMgr lists and trees, and then call it's PostFinalize callback before immediate transitioning to the Finalized state.

Finalized

The BaseProc has completed finalization and will imminently be deleted, with it's memory freed back to it's parent heap.

BaseProcBinder

Allows watching for the asynchronous creation of a BaseProc. On completion a BaseProcLink to that BaseProc can be retrieved.

BaseProcLink

A "hyperlink" reference to a BaseProc. Used to retrieve scoped "read" or "write" accessors to a BaseProc. The accessors follow the C++ "optional" pattern, where retrieving one can fail to retrieve the underlying BaseProc. There are a few rules regarding when an accessor is legal to acquire. Read accessors are the least strict, and succeed as long as the BaseProc has not processed a delete request. Write accessors have 3 different rulesets for anywhere, outside the system, and a strict inside the system.