Description
Provides fixed task-owned records of Ada task termination. The facility observes task exit only; it does not catch, resume, restart, or otherwise supervise a terminated task.
Attach
procedure Attach (Item : in out Monitor; T : Ada.Task_Identification.Task_Id)
Attach Item to the exact task represented by T. The caller must keep T's task object alive for this call and obey Task_Id lifetime rules. After Attach returns, the task object may be reclaimed while Item keeps the copied terminal result and completion gate alive. A task that already published its result is immediately observable. A created task that never began its body still never publishes. The operation performs no allocation and invokes no user callback.
Parameters
- Item
Detached monitor to attach
- T
Exact Ada task identity to observe
Raised exceptions
- Program_Error
Item is already attached, T is null, or T has no Flyology-owned task-result storage
Attached
function Attached (Item : Monitor) return Boolean
Report whether Item currently retains task-result storage.
Parameters
- Item
Monitor to inspect
Return value
True between successful Attach and Detach or finalization
Bounded_Exception_Message
type Bounded_Exception_Message is record
Length : Natural range 0 .. Exception_Message_Capacity := 0;
Truncated : Boolean := False;
Data : String (1 .. Exception_Message_Capacity) := (others => ' ');
end record;
Fixed exception message copied into a terminal result.
Record fields
- Length
Number of meaningful characters in Data
- Truncated
Whether the source message exceeded the fixed capacity
- Data
Fixed storage; characters after Length are unspecified
Bounded_Exception_Name
type Bounded_Exception_Name is record
Length : Natural range 0 .. Exception_Name_Capacity := 0;
Truncated : Boolean := False;
Data : String (1 .. Exception_Name_Capacity) := (others => ' ');
end record;
Fixed exception identity copied into a terminal result.
Record fields
- Length
Number of meaningful characters in Data
- Truncated
Whether the source name exceeded the fixed capacity
- Data
Fixed storage; characters after Length are unspecified
Detach
procedure Detach (Item : in out Monitor)
Release Item's observation reference. This is idempotent and does not cancel, abort, restart, or otherwise signal the observed task. A later Attach may reuse Item for another exact task.
Parameters
- Item
Monitor to detach
Exception_Message_Capacity
Exception_Message_Capacity : constant := 128;
Maximum retained exception-message bytes.
Exception_Name_Capacity
Exception_Name_Capacity : constant := 96;
Maximum retained exception-name bytes.
Exit_Cause
type Exit_Cause is (Normal_Completion, Unhandled_Exception, Abnormal_Completion);
Terminal classification copied from GNARL's task wrapper.
Enumeration literals
- Normal_Completion
The task body and its master completed normally
- Unhandled_Exception
An exception escaped the task body
- Abnormal_Completion
GNARL classified task exit as abnormal
Finish
procedure Finish (Operation : in out Wait_Operation; Observation : out Task_Observation)
Consume one terminal task-result operation. Timeout succeeds with a Not_Terminal observation; cancellation raises after consuming.
Parameters
- Operation
Terminal task-result operation
- Observation
Copied terminal result or Not_Terminal on timeout
Raised exceptions
- Program_Error
Runtime observation or subscription failed
- Operation_Cancelled
Operation was cancelled
Monitor
type Monitor is tagged limited private;
Limited exact-task observation handle. Attach retains only the fixed task-result sidecar; it neither retains the Ada task object nor follows another task that later occupies related application state. Finalization detaches automatically and never affects the observed task.
Observation_Status
type Observation_Status is (Not_Terminal, Terminal);
Availability of a task-owned terminal result.
Enumeration literals
- Not_Terminal
The task has not reached its terminal publication point
- Terminal
A fixed result was copied from the task-owned sidecar
Observe
function Observe (T : Ada.Task_Identification.Task_Id) return Task_Observation
Atomically copy T's terminal result without waiting. The result remains available until the task object is reclaimed. The caller must keep T's task object alive and obey Ada.Task_Identification's Task_Id lifetime rules. The operation performs no allocation and invokes no user callback. Only a task that begins executing its body publishes a result, so a task whose activation failed stays Not_Terminal even though Ada already reports it as terminated.
Parameters
- T
Task whose terminal state is observed
Return value
Terminal with a copied result, or Not_Terminal
Raised exceptions
- Program_Error
T is null, lacks Flyology-owned result storage, or the runtime and library result ABIs differ
Observe
function Observe (Item : Monitor) return Task_Observation
Atomically copy Item's terminal result without waiting. Unlike the Task_Id overload, this remains valid after target task-object reclamation. The operation performs no allocation or callback.
Parameters
- Item
Attached monitor
Return value
Terminal with a copied result, or Not_Terminal
Raised exceptions
- Program_Error
Item is detached or the runtime and library result ABIs differ
Operation_Cancelled
Operation_Cancelled : exception renames Flyology.Operations.Operation_Cancelled;
Raised by Finish after a scoped task-result wait is cancelled.
Task_Observation
type Task_Observation (Status : Observation_Status := Not_Terminal) is record
case Status is
when Not_Terminal =>
null;
when Terminal =>
Result : Task_Result;
end case;
end record;
One atomic observation. The discriminant prevents callers from reading a result that was not available.
Record fields
- Status
Whether a terminal result was copied
- Result
Terminal result when Status is Terminal
Task_Result
type Task_Result is record
Cause : Exit_Cause := Normal_Completion;
Exception_Name : Bounded_Exception_Name;
Exception_Message : Bounded_Exception_Message;
end record;
One immutable terminal observation. Exception fields are empty unless Cause is Unhandled_Exception.
Record fields
- Cause
GNARL terminal classification
- Exception_Name
Bounded fully qualified exception identity
- Exception_Message
Bounded message from the exception occurrence
Text
function Text (Item : Bounded_Exception_Message) return String
Return the meaningful exception-message characters.
Parameters
- Item
Bounded exception message
Return value
Copied exception message without unused fixed storage
Text
function Text (Item : Bounded_Exception_Name) return String
Return the meaningful exception-name characters.
Parameters
- Item
Bounded exception name
Return value
Copied exception name without unused fixed storage
Wait
function Wait (T : Ada.Task_Identification.Task_Id; Timeout : Duration := -1.0) return Task_Observation
Wait up to Timeout for T's terminal result and return a copied observation. A negative timeout waits indefinitely, zero only checks, and a positive value is a relative duration. A native caller blocks through ordinary GNARL protected-entry machinery; a lightweight caller suspends only its fiber. The operation is abortable, performs no polling, and must not be called from an Ada protected action. The caller must keep T's task object alive throughout the call. A task whose activation failed never publishes, so waiting on it returns Not_Terminal at the timeout and an indefinite wait would not return; supply a bounded Timeout when a task may have failed activation. Every runtime-level wait failure, including reclamation of T while this call is waiting, is reported as Program_Error rather than propagating a runtime exception.
Parameters
- T
Task whose terminal result is awaited
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Terminal with a copied result, or Not_Terminal on timeout
Raised exceptions
- Program_Error
T is null, lacks Flyology-owned result storage, or the runtime wait failed
Wait
function Wait (Item : Monitor; Timeout : Duration := -1.0) return Task_Observation
Wait up to Timeout through Item's retained completion gate. Timeout, blocking, abortability, lane behavior, and protected-action restrictions match the Task_Id overload. Detaching or finalizing Item concurrently with this call is erroneous; structured ownership must keep the monitor alive for every borrower.
Parameters
- Item
Attached monitor kept alive throughout the call
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Terminal with a copied result, or Not_Terminal on timeout
Raised exceptions
- Program_Error
Item is detached or the runtime wait failed
Wait
function Wait
(Set : not null access Flyology.Operations.Completion_Set'Class;
T : Ada.Task_Identification.Task_Id;
Timeout : Duration := -1.0) return Wait_Operation
Start a task-result wait without suspending the owner.
Parameters
- Set
Completion set that owns the operation slot
- T
Exact task identity, valid throughout this initiating call
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Started limited task-result operation
Wait
function Wait
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : Monitor'Class;
Timeout : Duration := -1.0) return Wait_Operation
Start a task-result wait from an attached retained monitor.
Parameters
- Set
Completion set that owns the operation slot
- Item
Attached source monitor retained by the new operation
- Timeout
Maximum relative wait; negative means indefinitely
Return value
Started limited task-result operation
Wait
procedure Wait
(T : Ada.Task_Identification.Task_Id; Timeout : Duration := -1.0; Operation : in out Wait_Operation)
Start or restart a task-id wait in an established operation object.
Parameters
- T
Exact task identity, valid throughout this initiating call
- Timeout
Maximum relative wait; negative means indefinitely
- Operation
Fresh or consumed task-result operation
Wait
procedure Wait (Item : Monitor'Class; Timeout : Duration := -1.0; Operation : in out Wait_Operation)
Start or restart a retained-monitor wait in an established operation.
Parameters
- Item
Attached source monitor
- Timeout
Maximum relative wait; negative means indefinitely
- Operation
Fresh or consumed task-result operation
Wait_Operation
type Wait_Operation is new Flyology.Operations.Operation with private;
First-class wait for one retained task result. The operation owns a sidecar reference after initiation, so the target task object and a source Monitor need not remain alive while the operation is pending.