Description
Runs a bounded set of handler tasks under one structured Serve call.
Example:
Server_Instance.Serve (Server, Listener, Context);
Current
function Current (Item : Server) return Snapshot
Read one protected lifecycle snapshot. Safe during Serve.
Parameters
- Item
Server to observe
Return value
Current counters and lifecycle flags
Failure_Origin
type Failure_Origin is (No_Failure, Handler_Callback, Admission_Loop);
Source of the first recorded failure.
Enumeration literals
- No_Failure
No failure has been recorded
- Handler_Callback
Handle or connection cleanup failed
- Admission_Loop
Accept or handler bookkeeping failed
First_Failure_Information
function First_Failure_Information (Item : Server) return String
Return retained information for the first failure, or an empty string. The text remains available after Serve raises Server_Failed.
Parameters
- Item
Server to inspect
Return value
First failure information, truncated to 2,048 characters
Handle
procedure Handle
(Context : in out Handler_Context;
Connection : in out Flyology.IO.Connections.Connection;
Peer : Flyology.IO.Sockets.Endpoint;
Cancellation : not null access Flyology.IO.Connections.Cancellation_Token)
Process one admitted connection. Handle owns no connection lifetime and should observe Cancellation during CPU-only work.
Parameters
- Context
Shared instance supplied to Serve
- Connection
Open connection owned by its handler task
- Peer
Accepted peer address
- Cancellation
One-shot server cancellation source
Handler_Context
type Handler_Context (<>) is limited private;
State shared by every concurrent Handle call. Mutable state must provide its own synchronization.
Handler_CPU
Handler_CPU : System.Multiprocessors.CPU_Range := System.Multiprocessors.Not_A_Specific_CPU;
CPU aspect for handlers. For lightweight tasks, 1 .. 127 selects a shared execution group and the default Not_A_Specific_CPU distributes handlers over the configured pool; for native tasks it retains Ada CPU affinity.
Handler_Model
Handler_Model : Flyology.Execution_Model := Flyology.Project_Default;
Fixed task designation for all handlers in this generic instance.
Request_Shutdown
procedure Request_Shutdown (Item : in out Server)
Idempotently stop new accepts. Active handlers drain according to the concurrent Serve call. Calling before Serve causes that call to take and close Listener without admitting connections.
Parameters
- Item
Server whose admission loop should stop
Raised exceptions
- Program_Error
The shutdown wake source cannot be signalled
Serve
procedure Serve
(Item : aliased in out Server;
Listener : in out Flyology.IO.Sockets.Socket_Type;
Context : aliased in out Handler_Context;
Drain_Timeout : Duration := Infinite)
Take sole closing ownership of Listener, leave it closed, and serve until shutdown or failure. Transient aborted admissions are retried and descriptor exhaustion backs off without becoming a recorded failure; structural listener errors still fail the server. The call returns only after all handler tasks terminate. Shutdown first stops admission. Infinite waits indefinitely; zero forces cancellation immediately; other values are seconds. One deadline covers the drain. Connection I/O wakes on cancellation, while CPU-only Handle code must poll Cancellation.Requested cooperatively. Lightweight handlers suspend on event-loop I/O; native handlers block their threads. Aborting the Serve caller joins its dependent handlers, closes the transferred listener exactly once, and leaves Item terminal; abort is deferred only across bounded ownership and cleanup transitions. On an exceptional return after ownership transfers, Ada does not guarantee scalar in-out copy-back. A retained numeric Listener value is stale and must not be closed or reused. The server attempts close once and releases its handle even when the syscall reports an error because the descriptor number may already have been recycled.
Parameters
- Item
One-shot server kept alive for the call
- Listener
Bound listening socket; transferred and always closed
- Context
Shared handler context kept alive for the call
- Drain_Timeout
Grace period before forced cancellation
Raised exceptions
- Program_Error
Listener, lifecycle, or wake source is invalid
- Server_Failed
A handler or admission failure was recorded
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when listener close fails
- Tasking_Error
Handler task activation fails
Server
type Server (Capacity : Positive) is limited private;
One-shot server object. Capacity is both the admission limit and the number of handler tasks created eagerly by Serve. Handler designation is fixed at activation and cannot change. Serve, Request_Shutdown, and Current coordinate through protected state. Request_Shutdown may precede the one permitted Serve call; once that call begins, every normal or exceptional return or caller abort leaves the server terminal. Keep the object alive until Serve returns or its caller task terminates. Listener cleanup is attempted at most once; finalization closes only a listener whose Serve cleanup has not begun.
Record fields
- Capacity
Handler task count and connection admission limit
Server_Failed
Server_Failed : exception;
Raised by Serve after one or more handler or admission failures.
Snapshot
type Snapshot is record
Running : Boolean;
Accepting : Boolean;
Shutdown_Requested : Boolean;
Forced_Cancellation : Boolean;
Active_Handlers : Natural;
Accepted_Connections : Natural;
Completed_Connections : Natural;
Cancelled_Connections : Natural;
Failures : Natural;
First_Failure : Failure_Origin;
end record;
Atomic lifecycle snapshot returned by Current.
Record fields
- Running
Serve is active or draining
- Accepting
Listener ownership and handler activation completed, and shutdown has not stopped admission
- Shutdown_Requested
Admission has been stopped
- Forced_Cancellation
Drain timeout required handler cancellation
- Active_Handlers
Handlers currently processing a connection
- Accepted_Connections
Cumulative accepted connections, saturating at Natural'Last
- Completed_Connections
Cumulative normal callback completions, saturating at Natural'Last
- Cancelled_Connections
Cumulative cancelled callbacks, saturating at Natural'Last
- Failures
Cumulative admission, callback, or cleanup failures
- First_Failure
Origin of the first failure