Description
Runs a bounded homogeneous group of child operations with structured Ada task lifetime. Configure creates Capacity lightweight worker tasks; Spawn copies operations into fixed scope storage and may start them immediately. Join or scope finalization closes admission and joins every worker, so Execute must observe its token and deadline when it can block indefinitely.
Configure
procedure Configure
(Item : in out Scope; Deadline : Ada.Real_Time.Time; Cancel_Siblings_On_Failure : Boolean := True)
Install inherited cancellation and an absolute monotonic deadline before Spawn. Ada.Real_Time.Time_Last means no deadline. Children always receive a scope-owned token. Parent cancellation is linked downward asynchronously, while failure and finalization cancel only this scope. The call allocates and activates Capacity lightweight workers; it is the only operation that may configure Item. When allocation or activation fails part way through, finalization of Item still stops and releases the workers that were already created. Parent is the scope's access discriminant, so Ada enforces that the borrowed token outlives Item.
Parameters
- Item
Task scope
- Deadline
Inherited absolute monotonic deadline
- Cancel_Siblings_On_Failure
Whether one failure cancels siblings
Raised exceptions
- Program_Error
Item was already configured or its identity space is exhausted
- Storage_Error
Worker or cancellation-monitor allocation fails
- Tasking_Error
Worker or cancellation-monitor activation fails
Execute
procedure Execute
(Input : Input_Type;
Token : access Flyology.Cancellation.Token;
Deadline : Ada.Real_Time.Time;
Result : out Result_Type)
Parameters
- Input
- Token
- Deadline
- Result
Input_Type
type Input_Type is private;
Invalid_Handle
Invalid_Handle : exception;
Raised when a handle does not identify a spawned operation.
Join
procedure Join (Item : in out Scope)
Close admission and wait for every submitted operation and worker. Exceptions are retained per operation and re-raised by Result. A second call after a successful Join is harmless. The caller waits through ordinary Ada tasking: a lightweight caller suspends cooperatively and a native caller blocks only its task's pthread.
Parameters
- Item
Configured task scope
Raised exceptions
- Program_Error
Item was not configured
Operation_Handle
type Operation_Handle is private;
Stable identity for one submitted operation. Handles are bound to the originating scope and are rejected by every other scope.
Result
function Result (Item : Scope; Handle : Operation_Handle) return Result_Type
Return an operation result or re-raise its captured exception with the original exception identity and retained message. Join must have completed.
Parameters
- Item
Joined task scope
- Handle
Operation handle
Return value
Operation result
Raised exceptions
- Program_Error
Join has not completed
- Invalid_Handle
Handle belongs to another scope or does not identify a submitted operation
Result_Type
type Result_Type is private;
Scope
type Scope
(Capacity : Positive;
Parent : access Flyology.Cancellation.Token)
is limited new Ada.Finalization.Limited_Controlled with private;
Bounded one-shot structured task group. Capacity is both the number of lightweight worker tasks created by Configure and the total number of operations accepted during the scope lifetime. The Parent token is borrowed and may be null; when present, cancellation is linked downward to the scope-owned token. Join closes admission. Finalization requests local cancellation, closes admission, and joins when Join was omitted; a cancellation request whose wake descriptor cannot be signalled is reported only after every worker has been joined and released.
Spawn
procedure Spawn (Item : in out Scope; Input : Input_Type; Handle : out Operation_Handle)
Submit one operation without exceeding Capacity. Input is copied before admission is committed; an exception from that copy propagates without consuming a slot or defining Handle. A worker may begin Execute before Spawn returns. Before invoking Execute, the worker records an already requested scope token as Operation_Cancelled and an expired deadline as Flyology.IO.Timeout_Error.
Parameters
- Item
Configured task scope
- Input
Operation input copied into scope storage
- Handle
Stable result handle
Raised exceptions
- Program_Error
Item is not configured or admission was closed
- Constraint_Error
Capacity operations were already accepted
Succeeded
function Succeeded (Item : Scope; Handle : Operation_Handle) return Boolean
Report whether an operation completed without exception. Join must have completed.
Parameters
- Item
Joined task scope
- Handle
Operation handle
Return value
True when Execute returned normally
Raised exceptions
- Program_Error
Join has not completed
- Invalid_Handle
Handle belongs to another scope or does not identify a submitted operation