Description
Runs a bounded homogeneous dynamic child family as one synchronous Ada scope. Storage is linear in Maximum_Children, no dependency matrix is allocated, and at most one manager is allocated lazily for each slot that is used. Allocated managers remain dependent on the Run scope for reuse and their storage is reclaimed after they terminate at the join boundary.
Accepting
function Accepting (Item : Family) return Boolean
Report whether Run validated the family and admission remains open.
Parameters
- Item
Family to inspect
Return value
True when Start may reserve a slot
Application_Context
type Application_Context (<>) is limited private;
Configuration_Error
Configuration_Error : exception;
Raised before admission opens when the common policy, id range, or control-plane placement is invalid.
Control_Group
Control_Group : Flyology.Execution_Groups.Group_Selecting_CPU := 127;
Current
function Current (Item : Family; Handle : Child_Handle) return Child_Snapshot
Copy the current snapshot for an exact generation-qualified handle.
Parameters
- Item
Family to inspect
- Handle
Exact logical child and generation
Return value
Fixed current snapshot
Raised exceptions
- Stale_Handle
Handle no longer identifies the slot
Current
function Current (Item : Family; Child : Child_Id) return Child_Snapshot
Observe the latest generation for one stable logical child id. This overload is read-only and does not authorize a generation operation.
Parameters
- Item
Family to inspect
- Child
Logical child id within this family
Return value
Latest fixed snapshot for the occupied slot
Raised exceptions
- Stale_Handle
Child is outside the family or currently free
Event_Capacity
Event_Capacity : Positive := 256;
Family
type Family is limited private;
One-shot family owner. Run is the Ada master boundary; admitted manager and generation tasks cannot outlive it. Admissions, copied requests, handles, recovery state, and events belong to this family incarnation. Reconstructing an owner creates an empty family with new controller authority; desired requests that must persist belong outside the family and must be reconciled and admitted again.
First_Child_Id
First_Child_Id : Child_Id;
Latest
function Latest (Item : Family; Child : Child_Id) return Child_Handle
Sample a generation-qualified handle for one occupied logical child. A concurrent restart may make the returned handle stale before use.
Parameters
- Item
Family to inspect
- Child
Logical child id within this family
Return value
Latest exact generation handle
Raised exceptions
- Stale_Handle
Child is outside the family or currently free
Maximum_Children
Maximum_Children : Positive;
Monitor_Capacity
Monitor_Capacity : Positive := 64;
Policy
Policy : Child_Specification;
Read_Events
procedure Read_Events
(Item : in out Family;
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, and Dropped reports an overwritten sequence gap. No formatting or callback occurs under the family lock.
Parameters
- Item
Family 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 Family; Handle : Child_Handle; Diagnostic : String)
Reject the exact running generation after a failed external health probe. Diagnostic is copied before entering controller state.
Parameters
- Item
Running family
- Handle
Exact current generation
- Diagnostic
Bounded application health diagnostic
Raised exceptions
- Stale_Handle
Handle is foreign, stale, or not running
Request
type Request is private;
Request_Shutdown
procedure Request_Shutdown (Item : in out Family)
Close admission and cooperatively stop every occupied slot. A request made before Run is retained through configuration. The call is nonblocking; Run remains the join boundary.
Parameters
- Item
Family to shut down
Restart
procedure Restart (Item : in out Family; Handle : Child_Handle)
Request bounded replacement of the exact running family generation. The common policy must be restart safe, locally recoverable, and not Never. Recovery budgets and backoff apply exactly as they do to automatic recovery.
Parameters
- Item
Running family
- Handle
Exact current generation
Raised exceptions
- Stale_Handle
Handle is foreign, stale, or not running
- Program_Error
The family policy does not permit local replacement
Run
procedure Run
(Item : aliased in out Family;
Context : aliased in out Application_Context;
Result : out Supervisor_Result)
Validate and run until explicit shutdown or terminal policy escalation. Start, Stop, Current, and Request_Shutdown may be called concurrently. A shutdown requested before Run is sticky and keeps admission closed.
Parameters
- Item
One-shot family owner
- Context
Application state retained by every live generation
- Result
Terminal result after every terminable child joins
Raised exceptions
- Configuration_Error
Family configuration is invalid
- Program_Error
Item was already run
- Tasking_Error
A manager task could not activate
Run_Nested
procedure Run_Nested
(Item : aliased in out Family;
Context : aliased in out Application_Context;
Parent : aliased in out Generation_Control;
Result : out Supervisor_Result)
Run a family under Parent's exact recovery incident. A stop request on Parent closes admission and begins family shutdown. A terminal family outcome reports the same incident through Parent rather than minting a second hierarchical attempt. Restarting Parent creates a new one-shot family; this operation does not replay admissions or preserve handles.
Parameters
- Item
One-shot nested family owner
- Context
Application state retained by every live generation
- Parent
Owning generation control and incident propagation path
- Result
Terminal result after every terminable child joins
Raised exceptions
- Configuration_Error
Family 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;
Input : Request;
Control : aliased in out Generation_Control;
Result : out Generation_Result)
Parameters
- Context
- Input
- Control
- Result
Stale_Handle
Stale_Handle : exception;
Raised when a generation-qualified handle no longer names its slot's current generation.
Start
procedure Start (Item : in out Family; Input : Request; Handle : out Child_Handle)
Copy Input into a reserved slot and publish admission only after the copy succeeds. Copy or finalization work is never performed while the family lock is held. Admission records current controller state rather than persistent application intent and is not replayed into another Family object.
Parameters
- Item
Running family with open admission
- Input
Typed generation input copied into family-owned storage
- Handle
Exact logical child and first generation
Raised exceptions
- Program_Error
Family is not running or is shutting down
- Constraint_Error
Every fixed slot is occupied
Stop
procedure Stop (Item : in out Family; Handle : Child_Handle)
Cooperatively stop the exact admitted or live generation. A terminated generation awaiting replacement backoff cannot stop its replacement.
Parameters
- Item
Running family
- Handle
Exact generation to stop
Raised exceptions
- Stale_Handle
Handle does not identify an admitted/live task
Wait_Termination
function Wait_Termination
(Item : in out Family; 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 atomic with respect to family lifecycle changes, so a rapid restart cannot be lost. 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 stops the child nor follows its replacement. Item must outlive the call.
Parameters
- Item
Family that issued Handle
- Handle
Exact admitted generation to observe
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Terminal, replaced, or timed-out fixed observation
Raised exceptions
- Stale_Handle
Handle is outside this family or predates any generation retained in its slot
- Constraint_Error
Monitor_Capacity waiters are already active