Description
Supplies the source-neutral protocol used by scoped operation providers. A provider starts one caller-owned operation, advances it on the owner task's stack, and either arms its next source or publishes a terminal outcome. These calls create no task, stack, callback thread, or heap object.
Arm_Deadline
procedure Arm_Deadline (Item : in out Operation'Class; Interval : Duration)
Set or replace one operation deadline. A nonpositive interval is due on the next completion-set drive. A deadline can coexist with readiness.
Parameters
- Item
Pending operation whose deadline changes
- Interval
Relative monotonic interval in seconds
Raised exceptions
- Operation_Error
Item is stale or terminal
Arm_Readiness
procedure Arm_Readiness (Item : in out Operation'Class; Sources : Readiness_Source_Array)
Arm several descriptor interests for one operation. Readiness of any source invokes Drive once; the driver must rearm its next complete set. Duplicate descriptor/direction pairs are accepted and coalesced by the completion-set wait. Every descriptor owner must outlive the operation.
Parameters
- Item
Pending operation to arm
- Sources
Nonempty bounded descriptor interests
Raised exceptions
- Operation_Error
Item is stale, terminal, already armed, a descriptor is invalid, or the source bound is exceeded
Arm_Readiness
procedure Arm_Readiness
(Item : in out Operation'Class; Descriptor : Interfaces.C.int; For_Write : Boolean)
Arm one descriptor source. A later readiness event invokes Drive on the owning task's stack. The descriptor owner must outlive the operation.
Parameters
- Item
Pending operation to arm
- Descriptor
Valid borrowed operating-system descriptor
- For_Write
True for write readiness; False for read readiness
Raised exceptions
- Operation_Error
Item is stale, terminal, or already armed
Clear_Deadline
procedure Clear_Deadline (Item : in out Operation'Class)
Remove one pending operation's deadline.
Parameters
- Item
Pending operation whose deadline is removed
Raised exceptions
- Operation_Error
Item is stale or terminal
Complete
procedure Complete (Item : in out Operation'Class; Result : Terminal_Outcome)
Publish one terminal outcome. The provider must release every runtime, kernel, descriptor, and buffer reference before this call.
Parameters
- Item
Pending operation to terminalize
- Result
Retained outcome interpreted by provider-specific Finish
Raised exceptions
- Operation_Error
Item is stale or not pending
Completion_Source
procedure Completion_Source
(Item : in out Operation'Class;
Read_Descriptor : out Interfaces.C.int;
Signal_Descriptor : out Interfaces.C.int)
Lazily create and return the shared completion wake descriptors for an externally completed provider such as positional file I/O.
Parameters
- Item
Pending operation whose set owns the wake source
- Read_Descriptor
Descriptor armed by the completion set
- Signal_Descriptor
Descriptor passed to the completion producer
Readiness_Source
type Readiness_Source is record
Descriptor : Interfaces.C.int;
For_Write : Boolean;
end record;
One descriptor interest retained by an operation while it is pending.
Record fields
- Descriptor
Valid borrowed operating-system descriptor
- For_Write
True for write readiness; False for read readiness
Readiness_Source_Array
type Readiness_Source_Array is array (Positive range <>) of Readiness_Source;
Bounded descriptor set armed as one operation source.
Reschedule
procedure Reschedule (Item : in out Operation'Class)
Ask the completion set to invoke one further bounded provider step on the owner task before it blocks for external readiness. This avoids recursive driving when a provider has buffered progress that needs no descriptor event, such as a TLS session consuming already-decrypted input. Each invocation must remain a bounded step.
Parameters
- Item
Pending operation to reschedule
Raised exceptions
- Operation_Error
Item is stale, terminal, or already armed
Rollback_Start
procedure Rollback_Start (Item : in out Operation'Class)
Return a just-started operation to its reusable idle state when provider preparation fails before any external source or kernel request retains it. This is the exception rollback path for explicit Rearm operations.
Parameters
- Item
Pending operation whose initiation did not publish effects
Raised exceptions
- Operation_Error
Item is stale or not pending
Signal_Completion
procedure Signal_Completion (Item : in out Operation'Class)
Signal the shared completion source previously established for Item. This is the producer side of Completion_Source for an Ada provider that retains a caller-owned operation node rather than a raw descriptor. The operation and its completion set must still be alive.
Parameters
- Item
Pending externally completed operation to notify
Start
procedure Start (Item : in out Operation'Class)
Reserve the operation's stable slot and mark it pending. Call this once before the provider's first Drive event.
Parameters
- Item
Fresh or previously consumed operation object
Raised exceptions
- Capacity_Error
The completion set has no reusable slot
- Operation_Error
Item already has a pending or terminal value