Description
Defines the bounded, generation-safe vocabulary for structured task supervision. Task-generation generics own application-defined Ada task types; controllers supply typed topology and policy. No supervised task is detached from its Ada master.
Abort_Requested
function Abort_Requested (Control : Generation_Control) return Boolean
Report whether an optional Ada abort request was published. This is for structured child runners; application callbacks normally inspect only the cancellation token.
Parameters
- Control
Active generation control
Return value
True after the stop grace interval requested abort
Active
function Active (Context : Incident_Context) return Boolean
Report whether Context identifies an active recovery cascade.
Parameters
- Context
Recovery context to inspect
Return value
True when an incident id, attempt, and deadline are present
Attempt
function Attempt (Context : Incident_Context) return Incident_Attempt
Return the active incident attempt.
Parameters
- Context
Active recovery context
Return value
Current attempt within the incident
Raised exceptions
- Program_Error
Context is inactive
Child
function Child (Handle : Child_Handle) return Child_Id
Return the logical identity carried by Handle.
Parameters
- Handle
Generation-qualified child handle
Return value
Stable logical child identity
Child_Handle
type Child_Handle is private;
Logical child plus exact generation. Supervisory operations must reject a handle whose generation is no longer current.
Child_Id
subtype Child_Id is Interfaces.Unsigned_64 range 1 .. Interfaces.Unsigned_64'Last;
Stable nonzero logical identity of one configured child. Capacity is a separate property of each supervisor instance.
Child_Snapshot
type Child_Snapshot is record
Id : Child_Id;
Generation : Supervision.Generation;
State : Child_State;
Task_Model : Flyology.Execution_Model;
Has_Group : Boolean;
Group : Flyology.Execution_Groups.Group_Id;
Termination : Termination_Summary;
Attempts : Interfaces.Unsigned_64;
Backoff : Ada.Real_Time.Time_Span;
Ready : Boolean;
Live : Boolean;
Escalated : Boolean;
end record;
Bounded observation of one configured logical child.
Record fields
- Id
Stable logical identity
- Generation
Current or most recently completed generation
- State
Current lifecycle
- Task_Model
Configured task execution model
- Has_Group
Whether Group is meaningful for a lightweight task
- Group
Configured lightweight execution group
- Termination
Last bounded termination information
- Attempts
Attempts admitted in the active incident
- Backoff
Current monotonic delay
- Ready
Whether the current generation completed its handshake
- Live
Whether an Ada task object for this generation may be alive
- Escalated
Whether recovery was forwarded to the parent
Child_Specification
type Child_Specification is record
Restart : Restart_Kind := Never;
Impact : Restart_Impact := Escalate;
Recovery : Recovery_Limits := Default_Recovery_Limits;
Stopping : Stop_Policy := Default_Stop_Policy;
Readiness_Timeout : Ada.Real_Time.Time_Span := Ada.Real_Time.Seconds (30);
Restart_Safe : Boolean := False;
Task_Model : Flyology.Execution_Model := Flyology.Project_Default;
Has_Group : Boolean := False;
Group : Flyology.Execution_Groups.Group_Id := Flyology.Execution_Groups.Group_Id'First;
end record;
Complete static policy for one logical child. Restart_Safe is an explicit application acknowledgement that a fresh generation may safely reacquire its owned resources and resume use of shared state. If the generation owns a nested one-shot controller, the acknowledgement also covers reconstruction of that controller and application-directed replay of its desired topology. Local automatic restart is rejected when it is False. Task_Model must be explicitly Flyology.Lightweight_Task or Flyology.Native_Task; Project_Default is rejected because supervision cannot resolve it to a concrete model for placement validation.
Record fields
- Restart
Child-level replacement selection
- Impact
Children affected by a local recovery incident
- Recovery
Monotonic restart limits and delays
- Stopping
Cooperative and optional abort policy
- Readiness_Timeout
Maximum interval before explicit readiness
- Restart_Safe
Application acknowledgement of restart safety
- Task_Model
Configured execution model reported in snapshots
- Has_Group
Whether Group applies to a lightweight generation
- Group
Configured lightweight execution group
Child_State
type Child_State is
(Configured,
Starting,
Ready,
Running,
Stopping,
Terminated,
Backing_Off,
Restarting,
Failed_Escalated,
Joined);
Observable lifecycle of one logical child.
Enumeration literals
- Configured
Policy is validated but no task object exists
- Starting
A new task object is activating or awaiting readiness
- Ready
The generation reported readiness but is not yet published
- Running
The ready generation is published to dependents
- Stopping
Cooperative shutdown or restart teardown is in progress
- Terminated
The task and its task-body finalization completed
- Backing_Off
A monotonic restart delay is pending
- Restarting
Policy admitted construction of a replacement
- Failed_Escalated
Local recovery ended or was escalated
- Joined
No task can publish again and all owned state is reclaimed
Current_Generation
function Current_Generation (Handle : Child_Handle) return Generation
Return the generation carried by Handle.
Parameters
- Handle
Generation-qualified child handle
Return value
Exact child generation
Default_Recovery_Limits
Default_Recovery_Limits : constant Recovery_Limits :=
(Burst_Attempts => 3,
Window => Ada.Real_Time.Seconds (5),
Total_Attempts => 10,
Initial_Backoff => Ada.Real_Time.Milliseconds (10),
Maximum_Backoff => Ada.Real_Time.Seconds (1),
Stability_Reset => Ada.Real_Time.Seconds (30),
Recovery_Deadline => Ada.Real_Time.Seconds (60));
Default bounded recovery policy used by child specifications.
Default_Stop_Policy
Default_Stop_Policy : constant Stop_Policy :=
(Grace => Ada.Real_Time.Seconds (5),
Request_Abort => False,
Abort_Observation => Ada.Real_Time.Seconds (1));
Default cooperative stop policy. Abort is not requested implicitly.
Diagnostic_Length
subtype Diagnostic_Length is Natural range 0 .. Maximum_Diagnostic_Length;
Valid used length within a fixed diagnostic buffer.
Event_Kind
type Event_Kind is
(Lifecycle_Changed,
Readiness_Published,
Stop_Published,
Restart_Admitted,
Restart_Completed,
Recovery_Escalated,
Child_Became_Stuck,
Supervisor_Stopped);
Observable reason for a supervisor event.
Enumeration literals
- Lifecycle_Changed
A child moved between lifecycle states
- Readiness_Published
A generation completed its readiness handshake
- Stop_Published
Cooperative cancellation was requested
- Restart_Admitted
A bounded recovery attempt was admitted
- Restart_Completed
Every affected replacement became ready
- Recovery_Escalated
Recovery was rejected or delegated upward
- Child_Became_Stuck
A live generation exceeded stop observation
- Supervisor_Stopped
Explicit structured shutdown began
Event_Sequence
subtype Event_Sequence is Interfaces.Unsigned_64;
Monotonic sequence used by bounded supervisor event rings. Zero is a valid initial cursor and is never assigned to a recorded event.
Exception_Name_Length
subtype Exception_Name_Length is Natural range 0 .. Maximum_Exception_Name_Length;
Valid used length within a fixed exception-name buffer.
Exception_Name_Text
function Exception_Name_Text (Item : Termination_Summary) return String
Return the meaningful fully qualified exception name, or the empty string when no exception name was retained.
Parameters
- Item
Bounded terminal summary
Return value
Retained exception name without unused fixed storage
Generation
subtype Generation is Interfaces.Unsigned_64 range 1 .. Interfaces.Unsigned_64'Last;
Nonzero identity of one task-object generation. A restart creates a new generation and a new Ada task identity.
Generation_Control
type Generation_Control is limited private;
Generation-local readiness and cancellation channel. A child receives a borrowed access value whose lifetime ends when its generation task joins. It must not retain that value or the returned cancellation token.
Generation_Observation
type Generation_Observation (Status : Generation_Observation_Status := Observation_Timed_Out) is record
case Status is
when Observation_Timed_Out =>
null;
when Generation_Terminated | Generation_Replaced =>
Snapshot : Child_Snapshot;
end case;
end record;
One generation-safe supervisor observation. A timeout carries no snapshot; completed observations contain only fixed copied state and do not retain a task object or supervisor-owned resource.
Record fields
- Status
Whether the generation terminated, was replaced, or the wait timed out
- Snapshot
Exact terminal snapshot or current replacement snapshot
Generation_Observation_Status
type Generation_Observation_Status is (Generation_Terminated, Generation_Replaced, Observation_Timed_Out);
Result of waiting for one exact supervised generation.
Enumeration literals
- Generation_Terminated
The named generation completed and its bounded terminal snapshot was retained
- Generation_Replaced
The logical child now names another generation; the returned snapshot describes that current generation
- Observation_Timed_Out
The deadline elapsed before either outcome
Generation_Result
type Generation_Result is record
Termination : Termination_Summary;
Reported_Ready : Boolean := False;
Incident : Incident_Context := No_Incident;
end record;
Completion returned by one structured generation runner after its local Ada master has joined the task and completed task-body finalization.
Record fields
- Termination
Bounded copied terminal information
- Reported_Ready
Whether readiness was published before completion
- Incident
Nested incident propagated by the generation, if any
Handle
function Handle (Control : Generation_Control) return Child_Handle
Return the exact logical child and generation represented by Control.
Parameters
- Control
Active generation control
Return value
Generation-qualified logical handle
Incident
function Incident (Context : Incident_Context) return Incident_Id
Return the active incident identity.
Parameters
- Context
Active recovery context
Return value
Stable incident identity
Raised exceptions
- Program_Error
Context is inactive
Incident_Attempt
subtype Incident_Attempt is Interfaces.Unsigned_64 range 1 .. Interfaces.Unsigned_64'Last;
One admitted recovery attempt within an incident.
Incident_Context
type Incident_Context is private;
Fixed recovery identity propagated through structured child calls. Inactive is the only representation that does not name an incident.
Incident_Id
subtype Incident_Id is Interfaces.Unsigned_64 range 1 .. Interfaces.Unsigned_64'Last;
Stable nonzero identity of one recovery cascade. The same value is propagated through nested supervisors until the cascade completes.
Is_Current
function Is_Current (Handle : Child_Handle; Id : Child_Id; Value : Generation) return Boolean
Test whether Handle names the supplied logical child and generation.
Parameters
- Handle
Generation-qualified child handle
- Id
Expected logical child identity
- Value
Expected generation
Return value
True only for an exact logical and generational match
Mark_Ready
procedure Mark_Ready (Control : in out Generation_Control)
Publish that activation and application initialization completed. This is a one-shot handshake; a second call or a call after stopping begins raises Program_Error.
Parameters
- Control
Active generation control
Raised exceptions
- Program_Error
Control is inactive, already ready, or stopping
Maximum_Diagnostic_Length
Maximum_Diagnostic_Length : constant := 512;
Maximum retained exception or policy diagnostic text.
Maximum_Exception_Name_Length
Maximum_Exception_Name_Length : constant := Flyology.Task_Results.Exception_Name_Capacity;
Maximum retained fully qualified exception-name characters.
Message_Text
function Message_Text (Item : Termination_Summary) return String
Return the meaningful diagnostic message, or the empty string when no message was retained.
Parameters
- Item
Bounded terminal summary
Return value
Retained message without unused fixed storage
No_Incident
No_Incident : constant Incident_Context;
Context used outside a recovery cascade.
Recovery_Deadline
function Recovery_Deadline (Context : Incident_Context) return Ada.Real_Time.Time
Return the inherited absolute monotonic recovery deadline.
Parameters
- Context
Active recovery context
Return value
Absolute deadline shared by the recovery hierarchy
Raised exceptions
- Program_Error
Context is inactive
Recovery_Incident
function Recovery_Incident (Control : Generation_Control) return Incident_Context
Return the recovery incident inherited by this generation. Initial startup normally returns No_Incident; replacement generations retain the incident and attempt that admitted them.
Parameters
- Control
Active generation control
Return value
Inherited recovery context or No_Incident
Recovery_Limits
type Recovery_Limits is record
Burst_Attempts : Positive;
Window : Ada.Real_Time.Time_Span;
Total_Attempts : Positive;
Initial_Backoff : Ada.Real_Time.Time_Span;
Maximum_Backoff : Ada.Real_Time.Time_Span;
Stability_Reset : Ada.Real_Time.Time_Span;
Recovery_Deadline : Ada.Real_Time.Time_Span;
end record;
Fixed recovery limits. Total_Attempts applies to one incident and is reset only after Stability_Reset. Window and all delays use monotonic Ada.Real_Time values. A zero Recovery_Deadline means no local recovery time; Time_Span_Last means no additional absolute limit.
Record fields
- Burst_Attempts
Maximum admitted attempts within Window
- Window
Sliding-window duration
- Total_Attempts
Maximum attempts in one recovery incident
- Initial_Backoff
Delay before the first replacement
- Maximum_Backoff
Cap for exponential delay
- Stability_Reset
Ready duration that closes the incident
- Recovery_Deadline
Maximum duration of one incident
Report_Cancellation
procedure Report_Cancellation (Control : in out Generation_Control)
Optionally override automatic task-result classification with cooperative cancellation. An uncaught Cancellation.Operation_Cancelled, or a normal return after the supervisor requested stop, is classified automatically. This operation remains useful when application code catches and suppresses cancellation from another source. Cancellation caused by supervisor shutdown is retained as Supervisor_Shutdown.
Parameters
- Control
Generation control borrowed by the reporting task
Raised exceptions
- Program_Error
No active generation exists or an outcome was already reported
Report_Escalation
procedure Report_Escalation (Control : in out Generation_Control; Context : Incident_Context)
Propagate a nested supervisor's active incident through this generation without creating another attempt. The call is accepted only while the exact generation remains active.
Parameters
- Control
Active outer generation control
- Context
Active incident returned by a nested supervisor
Raised exceptions
- Program_Error
Control or Context is inactive
Report_Exception
procedure Report_Exception
(Control : in out Generation_Control; Occurrence : Ada.Exceptions.Exception_Occurrence)
Optionally override automatic task-result classification with an exception that application code caught and suppressed. Exceptions that escape the task body are copied automatically after task finalization. This operation copies the occurrence immediately and remains available for source compatibility and deliberate semantic translation.
Parameters
- Control
Generation control borrowed by the reporting task
- Occurrence
Exception caught by the outer task-body handler
Raised exceptions
- Program_Error
No active generation exists or an outcome was already reported
Report_Normal_Return
procedure Report_Normal_Return (Control : in out Generation_Control)
Optionally override automatic task-result classification with normal completion. Task_Generations already observes an uncaught normal return; use this only when an application deliberately needs to publish a different semantic result after its owned resource scope finalized.
Parameters
- Control
Generation control borrowed by the reporting task
Raised exceptions
- Program_Error
No active generation exists or an outcome was already reported
Report_Unhealthy
procedure Report_Unhealthy (Control : in out Generation_Control; Diagnostic : String)
Reject this generation from inside its task after detecting a bounded health failure. The diagnostic is copied before cooperative stop is requested. On_Failure and Always policies treat this as a recoverable failure; the configured impact and recovery budgets still apply.
Parameters
- Control
Generation control borrowed by the reporting task
- Diagnostic
Application health diagnostic copied immediately
Raised exceptions
- Program_Error
No active generation exists or an outcome was already reported
Restart_Impact
type Restart_Impact is (Isolate_Child, Restart_Cohort, Restart_Dependents, Escalate);
Explicit effect of one child failure.
Enumeration literals
- Isolate_Child
Restart only the failed logical child
- Restart_Cohort
Restart the failed child and a named cohort
- Restart_Dependents
Restart the failed child and declared users
- Escalate
Do not recover at this supervisor node
Restart_Kind
type Restart_Kind is (Never, On_Failure, Always);
Child-level restart selection.
Enumeration literals
- Never
Do not replace a terminated generation
- On_Failure
Replace only after a failure-class termination
- Always
Replace after normal or failed termination, but never after explicit supervisor shutdown, a stuck child, or policy exhaustion
Same_Controller
function Same_Controller (Left, Right : Child_Handle) return Boolean
Report whether two handles were issued by the same process-local controller identity. Controller identities never migrate between supervisor objects or survive process restart.
Parameters
- Left
First generation-qualified handle
- Right
Second generation-qualified handle
Return value
True only when both handles came from the same controller
Stop_Policy
type Stop_Policy is record
Grace : Ada.Real_Time.Time_Span;
Request_Abort : Boolean;
Abort_Observation : Ada.Real_Time.Time_Span;
end record;
Cooperative stop policy. Request_Abort permits an Ada abort request after Grace expires; it does not promise bounded termination.
Record fields
- Grace
Cooperative cancellation interval
- Request_Abort
Whether to issue an optional abort request
- Abort_Observation
Additional observation interval before Stuck
Stop_Requested
function Stop_Requested (Control : Generation_Control) return Boolean
Report whether the supervisor requested cooperative stop.
Parameters
- Control
Active generation control
Return value
True after a stop request is published
Stopping
function Stopping
(Control : aliased in out Generation_Control) return not null access Flyology.Cancellation.Token
Return the generation-owned cancellation source. The value is borrowed and may be passed to task-aware Flyology I/O. It becomes invalid when the generation runner returns.
Parameters
- Control
Active generation control kept alive by the caller
Return value
Borrowed generation-owned cancellation source
Supervisor_Event
type Supervisor_Event is record
Sequence : Event_Sequence := 0;
Timestamp : Ada.Real_Time.Time := Ada.Real_Time.Time_First;
Kind : Event_Kind := Lifecycle_Changed;
Child : Child_Id := Child_Id'First;
Generation : Supervision.Generation := Supervision.Generation'First;
Before : Child_State := Configured;
After : Child_State := Configured;
Task_Model : Flyology.Execution_Model := Flyology.Project_Default;
Has_Group : Boolean := False;
Group : Flyology.Execution_Groups.Group_Id := Flyology.Execution_Groups.Group_Id'First;
Termination : Termination_Kind := No_Termination;
Incident : Incident_Context := No_Incident;
Backoff : Ada.Real_Time.Time_Span := Ada.Real_Time.Time_Span_Zero;
end record;
Fixed copied supervisor event. The event contains enough scalar policy state to explain ordering, restart admission, and escalation without logging from a protected action.
Record fields
- Sequence
Monotonic sequence within the supervisor instance
- Timestamp
Monotonic observation time
- Kind
Event classification
- Child
Logical child involved
- Generation
Exact child generation
- Before
Lifecycle state before the event
- After
Lifecycle state after the event
- Task_Model
Configured execution model
- Has_Group
Whether Group is meaningful
- Group
Configured lightweight execution group
- Termination
Bounded causal termination classification
- Incident
Recovery incident, if any
- Backoff
Admitted delay before replacement construction
Supervisor_Event_Array
type Supervisor_Event_Array is array (Positive range <>) of Supervisor_Event;
Caller-owned destination for copied bounded events.
Supervisor_Outcome
type Supervisor_Outcome is
(Shutdown_Completed, Startup_Failed, Recovery_Exhausted, Failure_Escalated, Child_Stuck);
Terminal outcome of a synchronous supervisor run.
Enumeration literals
- Shutdown_Completed
Explicit shutdown joined every child
- Startup_Failed
A child failed before initial readiness completed
- Recovery_Exhausted
Recovery limits rejected another generation
- Failure_Escalated
Child policy required the owning scope to fail
- Child_Stuck
A child remained live after the diagnostic stop policy
Supervisor_Result
type Supervisor_Result is record
Outcome : Supervisor_Outcome := Shutdown_Completed;
Child : Child_Id := Child_Id'First;
Generation : Supervision.Generation := Supervision.Generation'First;
Termination : Termination_Summary;
Incident : Incident_Context := No_Incident;
end record;
Typed terminal result returned only after every terminable child joins. A Child_Stuck result remains observable in snapshots, but synchronous Run cannot return it while the task is still alive.
Record fields
- Outcome
Terminal classification
- Child
Logical child that caused a non-shutdown outcome
- Generation
Generation that caused the outcome
- Termination
Bounded causal termination information
- Incident
Recovery cascade propagated to the owning scope
Termination_Kind
type Termination_Kind is
(No_Termination,
Normal_Return,
Unhandled_Exception,
Cancelled,
Supervisor_Shutdown,
Abnormal_Completion,
Activation_Failure,
Readiness_Timeout,
…,
Policy_Exhaustion);
Why one generation ceased to be usable.
Enumeration literals
- No_Termination
No generation has terminated
- Normal_Return
The task body returned normally
- Unhandled_Exception
GNARL observed an exception escaping the task
- Cancelled
The child observed cooperative cancellation
- Supervisor_Shutdown
The owning supervisor requested shutdown
- Abnormal_Completion
Ada reported abnormal task termination
- Activation_Failure
Task activation raised Tasking_Error
- Readiness_Timeout
Activation completed but readiness did not
- Restart_Requested
An exact-generation manual restart was requested
- Unhealthy
A health probe rejected the running generation
- Stop_Timeout
The cooperative grace deadline expired
- Stuck
Abort was omitted, deferred, or could not be observed
- Policy_Exhaustion
Recovery limits rejected another attempt
Termination_Summary
type Termination_Summary is record
Kind : Termination_Kind := No_Termination;
Exception_Id : Ada.Exceptions.Exception_Id := Ada.Exceptions.Null_Id;
Exception_Name_Length : Supervision.Exception_Name_Length := 0;
Exception_Name_Truncated : Boolean := False;
Exception_Name : String (1 .. Maximum_Exception_Name_Length) := (others => ' ');
Task_Id : Ada.Task_Identification.Task_Id := Ada.Task_Identification.Null_Task_Id;
Message_Length : Diagnostic_Length := 0;
Message_Truncated : Boolean := False;
Message : String (1 .. Maximum_Diagnostic_Length) := (others => ' ');
end record;
Bounded failure information safe after an exception occurrence and task object are gone. Task_Id is diagnostic only and must not be used to control a replacement generation.
Record fields
- Kind
Classified terminal outcome
- Exception_Id
Retained library-level exception identity when an occurrence was classified directly; automatic task-exit observation retains the portable name and leaves this Null_Id
- Exception_Name_Length
Used prefix of Exception_Name
- Exception_Name_Truncated
Whether the source name exceeded its fixed task-result capacity
- Exception_Name
Bounded fully qualified exception name
- Task_Id
Ada identity of the terminated generation
- Message_Length
Used prefix of Message
- Message_Truncated
Whether the source message exceeded retained storage
- Message
Bounded copied diagnostic text