Description
Supplies an application-owned bounded native-task boundary. A fixed pool runs CPU-heavy or blocking foreign work without occupying event-loop pthreads. Admission is nonblocking and outstanding result storage is bounded independently from worker count. Executor finalization joins every worker. Execute must therefore honor its token/deadline when it can block; foreign calls that cannot be interrupted require process isolation for a bounded application shutdown.
An Operation_Handle is declared for one aliased Executor and may be reused only after Await or Abandon consumes its accepted operation. Await keeps ordinary synchronous Ada semantics: lightweight callers suspend on the protected entry while native callers block only their pthread.
Abandon
procedure Abandon (Item : aliased in out Executor; Handle : in out Operation_Handle)
Relinquish one accepted result and request cooperative cancellation. Running foreign code may continue until it returns, but its slot is reclaimed automatically at completion.
Parameters
- Item
Owning executor
- Handle
Accepted operation handle
Raised exceptions
- Invalid_Handle
Handle is inactive, stale, or belongs to another executor
- Program_Error
The operation's cancellation wake cannot be signalled; the handle is still consumed
Await
procedure Await
(Item : aliased in out Executor;
Handle : in out Operation_Handle;
Result : out Result_Type;
Token : access Flyology.Cancellation.Token := null;
Deadline : Ada.Real_Time.Time := Ada.Real_Time.Time_Last)
Wait for one accepted operation, return its result, or re-raise its captured exception with the original exception identity and retained message. Copying a result into bounded storage runs Result_Type assignment, so an exception from that copy becomes the operation's captured outcome instead of a successful result. Deadline bounds only this wait; the operation receives the separate deadline supplied to Submit. Ada.Real_Time.Time_Last means no wait deadline. Cancellation or deadline expiry abandons the result and requests the executor-owned operation token. Each handle is consumed exactly once; finalizing an unconsumed handle performs the same abandon.
Parameters
- Item
Application-owned executor
- Handle
Previously accepted single-use handle
- Result
Completed result
- Token
Optional cancellation source for the waiting caller
- Deadline
Absolute deadline for the waiting caller
Raised exceptions
- Invalid_Handle
Handle is inactive, stale, or belongs to another executor
- Operation_Cancelled
Flyology.Cancellation.Operation_Cancelled is raised when Token is requested before the result is consumed- Timeout_Error
Flyology.IO.Timeout_Error is raised when Deadline expires before the result is consumed
- Program_Error
A cancellation wake source 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
Executor
type Executor
(Workers : Positive;
Capacity : Positive)
is limited new Ada.Finalization.Limited_Controlled with private;
Application-owned executor. Workers is the aggregate native pthread bound; Capacity bounds queued, running, and completed-but-unclaimed operations.
Executor_Statistics
type Executor_Statistics is record
Accepted_Submissions : Interfaces.Unsigned_64 := 0;
Rejected_Submissions : Interfaces.Unsigned_64 := 0;
Successful_Executions : Interfaces.Unsigned_64 := 0;
Failed_Executions : Interfaces.Unsigned_64 := 0;
Abandoned_Operations : Interfaces.Unsigned_64 := 0;
Outstanding_Operations : Natural := 0;
Queued_Operations : Natural := 0;
Running_Operations : Natural := 0;
Peak_Outstanding : Natural := 0;
end record;
Point-in-time executor counters. Cumulative counters wrap modulo 2**64. Outstanding includes queued, running, and completed results that have not yet been consumed or abandoned.
Record fields
- Accepted_Submissions
Operations admitted since initialization
- Rejected_Submissions
Submissions refused by bounded admission
- Successful_Executions
Execute calls that returned normally
- Failed_Executions
Execute calls that raised an exception
- Abandoned_Operations
Accepted handles relinquished by callers
- Outstanding_Operations
Currently occupied operation slots
- Queued_Operations
Operations awaiting a native worker
- Running_Operations
Operations currently executing natively
- Peak_Outstanding
Highest occupied-slot count observed
Input_Type
type Input_Type is private;
Invalid_Handle
Invalid_Handle : exception;
Raised for a stale, rejected, or already consumed operation handle.
Operation_Handle
type Operation_Handle (Owner : not null access Executor) is limited private;
Single-use identity for one accepted operation. The access discriminant makes Ada reject a handle whose lifetime could exceed its executor. An inactive handle may be reused for another Submit to the same executor.
Record fields
- Owner
Borrowed executor that must outlive the handle
Result_Type
type Result_Type is private;
Shutdown
procedure Shutdown (Item : in out Executor)
Stop admission, request cancellation for every outstanding operation, and join all native workers. Shutdown is terminal and idempotent; Start raises Program_Error afterward. Execute must observe its executor-owned token or deadline for this call to remain bounded. Explicit Shutdown reports cleanup errors before scope exit; controlled finalization performs the same cleanup when a started executor leaves its task master. If cancellation wake signaling fails, terminal cancellation remains recorded; cleanup completes before Shutdown propagates Program_Error.
Parameters
- Item
Application-owned executor
Raised exceptions
- Program_Error
An executor-owned cancellation wake could not be signaled
Start
procedure Start (Item : aliased in out Executor)
Activate the fixed worker pool before concurrent submissions. Start is idempotent while the executor remains open and must be called by the owning application during setup.
Parameters
- Item
Application-owned executor
Raised exceptions
- Program_Error
Shutdown has started
- Storage_Error
Worker storage allocation fails
- Tasking_Error
Native worker activation fails
Statistics
function Statistics (Item : Executor) return Executor_Statistics
Read executor admission, execution, and occupancy counters atomically. This is an observability operation; it does not wait for work or change executor state.
Parameters
- Item
Executor to inspect
Return value
Point-in-time executor statistics
Submit
procedure Submit
(Item : aliased in out Executor;
Input : Input_Type;
Token : access Flyology.Cancellation.Token;
Deadline : Ada.Real_Time.Time;
Handle : in out Operation_Handle;
Accepted : out Boolean)
Submit without waiting. Accepted is false when bounded storage is full, shutdown has begun, or an idle worker has not yet reached its dispatch rendezvous; Handle then remains inactive and reusable. The executor samples Token at submission and gives Execute an executor-owned cancellation token; it never retains the caller's token. Deadline is an absolute monotonic deadline passed to Execute. A worker converts a token already requested before dispatch to Operation_Cancelled and an already expired deadline to Flyology.IO.Timeout_Error. An accepted handle must not outlive Item.
Parameters
- Item
Application-owned executor
- Input
Operation input copied into bounded storage
- Token
Optional borrowed cancellation token
- Deadline
Absolute monotonic deadline
- Handle
Single-use result handle when accepted
- Accepted
Whether bounded admission succeeded
Raised exceptions
- Program_Error
Start has not completed
- Invalid_Handle
Handle belongs to another executor or already identifies an accepted operation