Shaft::baseproc - Revision history

Watertoon: Remove "base procedure" for lack of source

2026-02-16T08:58:21Z

Remove "base procedure" for lack of source

← Older revision		Revision as of 08:58, 16 February 2026
Line 1:		Line 1:
	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.		Shaft::baseproc implements a concurrent actor framework based on scheduling units called a "BaseProc". BaseProcs can be asynchronously created by an application and later inserted into the system and modified via requests.

	=== BaseProcMgr ===		=== BaseProcMgr ===

Watertoon: Change name of PendingActive and Active to Ready and Calc based on totk ai nodes QueryGenericIsSleepOrReady and QueryActorHolderIsCalcOrPauseState

2026-02-12T06:27:19Z

Change name of PendingActive and Active to Ready and Calc based on totk ai nodes QueryGenericIsSleepOrReady and QueryActorHolderIsCalcOrPauseState

← Older revision		Revision as of 06:27, 12 February 2026
Line 2:		Line 2:

	=== BaseProcMgr ===		=== 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.		Manages BaseProcs and BaseProc related sub-managers. BaseProcs with the Calc, Sleeping, or Paused states 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 ====		==== Lifecycle ====
Line 11:		Line 11:

	===== Building =====		===== 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.		The system is building the job graph. BaseProcs in the Calc state will insert their jobs, and paused or sleeping BaseProcs will instead insert their sleep job if they have one.

	===== BaseProc Processing =====		===== BaseProc Processing =====
Line 26:		Line 26:

	==== Lifecycle ====		==== Lifecycle ====
	A BaseProc has 12 states ~~grouped~~ into 4 "cycles"; initialization (3), live (4), removal (3), and finalization (2).		A BaseProc has 12 states one can logically group into 4 "cycles"; initialization (3), live (4), removal (3), and finalization (2).

	===== Initialization =====		===== Initialization =====
Line 41:		Line 41:

	===== Live =====		===== 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.		This group of states represents a BaseProc that is "live" in the system. The initial state after "PostInitialize" succeeds is Ready, from there a BaseProc can move between Calc, Sleeping, or Paused.

	====== ~~PendingActive~~ ======		====== Ready ======
	The initial "Live" state of a BaseProc. RequestCancelSleep or RequestCancelPause can be used to attempt to ~~activate~~ the BaseProc.		The initial "Live" state of a BaseProc. RequestCancelSleep or RequestCancelPause can be used to attempt to change the BaseProc to Calc.

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

	====== Sleeping ======		====== 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.		A heavyweight break in a BaseProc's processing. The BaseProc's sleep job will be used in job graph building. RequestCancelSleep will attempt to change the BaseProc to Calc.

	====== Paused ======		====== Paused ======

Watertoon: Write a bit about shaft::baseproc lifecycles.

2025-10-22T01:53:54Z

Write a bit about shaft::baseproc lifecycles.

New page

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.