Description
Runs bounded queued work in a lexical set of ordinary Ada tasks.
Run is deliberately a blocking structured scope. No worker outlives Run, its shared Context, or the Pool object. Submit may be called before or concurrently with Run. Request_Shutdown closes admission, requests the shared stopping token, and drains jobs accepted before closure.
Current
function Current (Item : Pool) return Snapshot
Sample current lifecycle, work, and queue state.
Parameters
- Item
Pool to inspect
Return value
Current snapshot
First_Failure_Information
function First_Failure_Information (Item : Pool) return String
Return retained information for the first failure, or an empty string. The text remains available after Run raises Pool_Failed.
Parameters
- Item
Pool to inspect
Return value
First exception information, truncated to 2,048 characters
Job_Type
type Job_Type is private;
Definite value transferred by copy to one worker.
Pool
type Pool
(Worker_Count : Positive;
Queue_Capacity : Positive)
is limited private;
One-shot structured pool with a fixed worker count and bounded FIFO. The object must outlive Run and every concurrent Submit or shutdown call. Jobs may be preloaded before Run up to Queue_Capacity.
Record fields
- Worker_Count
Tasks created by Run
Tasks created by Run
- Queue_Capacity
Maximum buffered jobs
Maximum buffered jobs
Pool_Failed
Pool_Failed : exception;
Raised by Run after all workers join when at least one callback or worker-lifecycle failure was recorded.
Process
procedure Process
(Context : in out Worker_Context;
Job : Job_Type;
Stopping : not null access Flyology.Cancellation.Token)
Process one job. Stopping is requested when shutdown begins or a worker reports a failure. A callback may pass it to task-aware I/O or inspect it during CPU-only work.
Parameters
- Context
Shared instance supplied to Run
- Job
One value removed from the bounded FIFO
- Stopping
Shared one-shot shutdown source
Request_Shutdown
procedure Request_Shutdown (Item : in out Pool)
Idempotently close admission and request the shared stopping token. Workers continue removing all jobs accepted before closure, then join. Once shutdown mutation begins, caller abort is deferred until the lifecycle flag, queue closure, and token wake have all been attempted.
Parameters
- Item
Pool to stop
Raised exceptions
- Program_Error
A borrowed cancellation source cannot be woken
Run
procedure Run
(Item : aliased in out Pool;
Context : aliased in out Worker_Context)
Create exactly Worker_Count dependent tasks and wait for shutdown. Run returns only after the closed queue drains and all workers terminate. The call and Pool are one-shot even after an exceptional return or caller abort; abnormal exit closes admission and terminalizes the pool.
Parameters
- Item
Pool kept alive for the complete worker scope
- Context
Shared callback state kept alive for the complete scope
Raised exceptions
- Program_Error
Run was already called
- Pool_Failed
One or more callback or worker failures occurred
- Tasking_Error
Worker activation fails
Snapshot
type Snapshot is record
Running : Boolean;
Shutdown_Requested : Boolean;
Active_Workers : Natural;
Pending_Jobs : Natural;
Completed_Jobs : Natural;
Cancelled_Jobs : Natural;
Failures : Natural;
end record;
Current pool lifecycle and work counters. Pending_Jobs is sampled from the channel separately from the remaining protected lifecycle fields; it may therefore reflect an immediately adjacent state transition.
Record fields
- Running
Run currently owns its worker scope
- Shutdown_Requested
Admission has been closed or is closing
- Active_Workers
Callbacks currently executing
- Pending_Jobs
Jobs currently buffered
- Completed_Jobs
Callbacks that returned normally, saturating
- Cancelled_Jobs
Callbacks that propagated Operation_Cancelled, saturating
- Failures
Callback or lifecycle failures, saturating
Submit
procedure Submit
(Item : in out Pool;
Job : Job_Type;
Accepted : out Boolean)
Submit one job, waiting for bounded queue capacity. Accepted is False after shutdown; no exception is used for this expected terminal state.
Parameters
- Item
Pool whose queue receives Job
- Job
Value copied into the queue
- Accepted
Whether the job was accepted
Submit
procedure Submit
(Item : in out Pool;
Job : Job_Type;
Timeout : Duration;
Result : out Submit_Result)
Submit one job within a relative deadline. Negative Timeout waits indefinitely and zero is an immediate attempt.
Parameters
- Item
Pool whose queue receives Job
- Job
Value copied into the queue
- Timeout
Deadline interval in seconds
- Result
Acceptance, closure, or timeout outcome
Submit_Result
type Submit_Result is (Job_Accepted, Pool_Closed, Submit_Timed_Out);
Outcome of a timed submission.
Enumeration literals
- Job_Accepted
The job entered the bounded FIFO
- Pool_Closed
Shutdown rejected the job
- Submit_Timed_Out
Capacity remained full through the deadline
Worker_Context
type Worker_Context (<>) is limited private;
State shared by concurrent Process calls. Mutable state must provide its own synchronization.
Worker_CPU
Worker_CPU : System.Multiprocessors.CPU_Range :=
System.Multiprocessors.Not_A_Specific_CPU;
CPU aspect for every worker. For lightweight tasks, 0 .. 127 selects an execution group; for native tasks it retains Ada affinity semantics.
Worker_Model
Worker_Model : Flyology.Execution_Model := Flyology.Project_Default;
Fixed task designation for every worker in this generic instance.