Description
Runs a typed, fixed static topology as a synchronous structured scope. Recovery is coordinated as one stop, join, backoff, start, and readiness transaction over an isolated child, a named cohort, or declared dependent closure. Nested calls retain one incident and attempt identity.
Application_Context
type Application_Context (<>) is limited private;
Child_Kind
type Child_Kind is (<>);
Cohort_Member
function Cohort_Member (Trigger : Child_Kind; Member : Child_Kind) return Boolean
Parameters
- Trigger
- Member
Return value
Configuration_Error
Configuration_Error : exception;
Raised before task creation when ids, policies, dependencies, cohorts, recovery limits, or control-plane placement are invalid.
Control_Group
Control_Group : Flyology.Execution_Groups.Group_Selecting_CPU := 127;
Current
function Current (Item : Supervisor; Child : Child_Kind) return Child_Snapshot
Sample one logical child. The snapshot contains only fixed copied state and may describe an immediately adjacent transition. Before Run has installed its validated configuration, this returns a Configured view constructed outside the controller lock.
Parameters
- Item
Supervisor to inspect
- Child
Static child kind
Return value
Current bounded child snapshot
Depends_On
function Depends_On (Child : Child_Kind; Prerequisite : Child_Kind) return Boolean
Parameters
- Child
- Prerequisite
Return value
Event_Capacity
Event_Capacity : Positive := 256;
Latest
function Latest (Item : Supervisor; Child : Child_Kind) return Child_Handle
Sample the exact current generation handle for Child. The handle may become stale immediately after return, but Wait_Termination will then report Generation_Replaced rather than observing a replacement as the original task.
Parameters
- Item
Running supervisor to inspect
- Child
Static child kind
Return value
Exact current child and generation
Raised exceptions
- Program_Error
Configuration is not installed or Child has not started its first generation
Logical_Id
function Logical_Id (Child : Child_Kind) return Child_Id
Parameters
- Child
Return value
Monitor_Capacity
Monitor_Capacity : Positive := 64;
Read_Events
procedure Read_Events
(Item : in out Supervisor;
Cursor : in out Event_Sequence;
Events : out Supervisor_Event_Array;
Count : out Natural;
Dropped : out Event_Sequence)
Copy events after Cursor in ascending sequence order. Cursor advances to the last copied event. If older events were overwritten, Dropped is the exact sequence gap before the first copied event. The caller controls the destination bound and no callback or logging occurs in the lock.
Parameters
- Item
Supervisor to inspect
- Cursor
Last sequence already consumed, or zero initially
- Events
Caller-owned fixed destination
- Count
Number of initialized leading elements in Events
- Dropped
Number of unavailable events before the copied range
Report_Unhealthy
procedure Report_Unhealthy
(Item : in out Supervisor; Child : Child_Kind; Handle : Child_Handle; Diagnostic : String)
Reject the exact running generation after a failed external health probe. Diagnostic is copied before entering controller state. Recovery follows the child policy; an Escalate impact terminates the node.
Parameters
- Item
Running static supervisor
- Child
Typed static child
- Handle
Exact current generation
- Diagnostic
Bounded application health diagnostic
Raised exceptions
- Stale_Handle
Handle is foreign, stale, or not running
Request_Shutdown
procedure Request_Shutdown (Item : in out Supervisor)
Idempotently begin reverse dependency order shutdown. A request made before Run or while configuration callbacks execute is retained and prevents child creation. Each live child first receives cooperative cancellation, followed by its configured optional abort request. Deadlines classify progress but do not bound this call or guarantee termination.
Parameters
- Item
Supervisor whose Run call should stop
Restart
procedure Restart (Item : in out Supervisor; Child : Child_Kind; Handle : Child_Handle)
Request bounded recovery of the exact running generation using its configured restart impact, stop policy, and recovery budgets. The child must be restart safe, locally recoverable, and have a restart policy other than Never.
Parameters
- Item
Running static supervisor
- Child
Typed static child
- Handle
Exact current generation
Raised exceptions
- Stale_Handle
Handle is foreign, stale, or not running
- Program_Error
Child is not configured for local replacement
Run
procedure Run
(Item : aliased in out Supervisor;
Context : aliased in out Application_Context;
Result : out Supervisor_Result)
Validate configuration, create bounded lightweight manager tasks, and run until explicit shutdown or a terminal child outcome. The call returns only after every terminable child generation and manager joins. A stuck child remains observable and necessarily prevents return.
Parameters
- Item
One-shot supervisor object kept alive for the complete call
- Context
Application state kept alive for every generation
- Result
Typed terminal result
Raised exceptions
- Configuration_Error
Static configuration is invalid
- Program_Error
Run was already called
- Tasking_Error
A manager task could not activate
Run_Nested
procedure Run_Nested
(Item : aliased in out Supervisor;
Context : aliased in out Application_Context;
Parent : aliased in out Generation_Control;
Result : out Supervisor_Result)
Run a nested supervisor under Parent's exact recovery incident. A stop request on Parent begins nested shutdown, and this call returns only after every terminable nested generation and manager joins. If the nested node escalates, the same incident is reported through Parent so the owning node does not mint or count another attempt.
Parameters
- Item
One-shot nested supervisor object
- Context
Application state kept alive for every generation
- Parent
Owning generation control and incident propagation path
- Result
Typed terminal result
Raised exceptions
- Configuration_Error
Static configuration is invalid
- Program_Error
Item was already run or Parent is inactive
- Tasking_Error
A manager task could not activate
Run_One_Generation
procedure Run_One_Generation
(Context : aliased in out Application_Context;
Child : Child_Kind;
Control : aliased in out Generation_Control;
Result : out Generation_Result)
Construct and join exactly one new Ada task generation. Applications normally dispatch to an instance of Flyology.Supervision.Task_Generations; the Children package remains a convenience adapter for procedure bodies. The operation must not return while its generation task or resources remain live.
Parameters
- Context
Application state owned by the enclosing Run call
- Child
Logical static child kind
- Control
Fresh generation readiness and cancellation channel
- Result
Terminal value available only after the generation joins
Specification
function Specification (Child : Child_Kind) return Child_Specification
Parameters
- Child
Return value
Stale_Handle
Stale_Handle : exception;
Raised when an exact-generation command does not identify the current live generation owned by this controller.
Subtree_Recovery
Subtree_Recovery : Recovery_Limits := Default_Recovery_Limits;
Supervisor
type Supervisor is limited private;
One-shot static supervisor. Run is the ownership boundary and must be called from one task. Current and Request_Shutdown may be called safely by other tasks. A shutdown requested before or during validation is sticky and prevents manager activation. Storage is fixed by Child_Kind; no per-restart allocation is performed by the controller.
Wait_Termination
function Wait_Termination
(Item : in out Supervisor; Child : Child_Kind; Handle : Child_Handle; Timeout : Duration := -1.0)
return Generation_Observation
Wait for Handle's exact generation to terminate or be replaced. The registration and current-generation check are one protected action, so termination cannot be lost between them. A negative timeout waits indefinitely, zero only checks, and a positive value is relative. The call is abortable, must not be made from a protected action, and neither affects the child nor follows a replacement generation. Item must outlive the call.
Parameters
- Item
Supervisor that owns Handle
- Child
Typed static child expected in Handle
- Handle
Exact generation to observe
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Terminal, replaced, or timed-out fixed observation
Raised exceptions
- Program_Error
Configuration is absent, Handle names another child, or Handle predates the first generation
- Constraint_Error
Monitor_Capacity waiters are already active