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, 0 .. 127 selects a shared execution group; 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. 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 object retains authoritative closing ownership until cleanup succeeds or it is finalized.
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
- Flyology
.IO.Sockets.Socket_Error 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 leaves the server terminal. Keep the object alive until Serve returns. If listener cleanup fails, the object retains closing ownership for a retry when it is finalized.
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;
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
- 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