Description
Provides a readable one-shot descriptor for protected cancellation state.
Example:
Flyology.Wake_Sources.Signal (Wake);
Consume
procedure Consume (Item : in out Source)
Consume one pending signal while retaining the descriptor generation.
Parameters
- Item
Serialized source with a pending signal
Raised exceptions
- Program_Error
No signal is pending or reading fails
Consume_All
procedure Consume_All (Item : in out Source)
Consume every signal currently pending while retaining the descriptor generation. This is intended for coalesced completion notifications; use Consume when each byte represents one independently counted event.
Parameters
- Item
Serialized source with at least one pending signal
Raised exceptions
- Program_Error
No signal is pending or reading fails
Descriptor
function Descriptor (Item : Source) return Interfaces.C.int
Borrow the current readable descriptor without transferring ownership.
Parameters
- Item
Source to inspect
Return value
Read descriptor, or -1 before Ensure or after Release
Ensure
procedure Ensure (Item : in out Source)
Lazily allocate a nonblocking close-on-exec descriptor pair. Repeated calls before Release are harmless.
Parameters
- Item
Serialized source to initialize
Raised exceptions
- Program_Error
Descriptor creation or configuration fails
Release
procedure Release (Item : in out Source)
Close both owned descriptors. Repeated calls are harmless. A later Ensure creates a new descriptor generation.
Parameters
- Item
Serialized source whose descriptors are released
Signal
procedure Signal (Item : in out Source)
Make Item's read end ready. Repeated signals remain readable until Consume or Release; this operation does not consume or close the source.
Parameters
- Item
Serialized source to signal
Raised exceptions
- Program_Error
Descriptor creation or signaling fails
Signal_Attempt_Result
type Signal_Attempt_Result is (Signal_Delivered, Signal_Interrupted, Signal_Failed);
Result of one borrowed-descriptor signal attempt.
Enumeration literals
- Signal_Delivered
One byte was written or readiness was already coalesced by a full nonblocking source
- Signal_Interrupted
The one syscall was interrupted before writing
- Signal_Failed
The descriptor or syscall result was invalid
Signal_Borrowed
procedure Signal_Borrowed (Descriptor : Interfaces.C.int)
Signal through the borrowed write descriptor returned by Signal_Descriptor. The Source must outlive the call. EINTR is retried; the nonblocking EAGAIN case is a coalesced success. This operation retains and closes no descriptor and must not be called while holding a protected lock because an unbounded signal sequence may delay retry.
Parameters
- Descriptor
Borrowed live write descriptor; concurrent borrowed signals are permitted while the owning Source cannot be released
Raised exceptions
- Program_Error
Descriptor is invalid or signaling fails
Signal_Descriptor
function Signal_Descriptor (Item : Source) return Interfaces.C.int
Borrow the descriptor used to signal Item. This is an internal provider boundary; callers must not read, close, or retain it after Item leaves scope.
Parameters
- Item
Initialized source to inspect
Return value
Signal descriptor, or -1 before Ensure or after Release
Source
type Source is new Ada.Finalization.Limited_Controlled with private;
Controlled owner of a lazily created descriptor pair. Operations on the Source object are intentionally unsynchronized: place Source inside a protected object or otherwise serialize every call. Concurrent Signal_Borrowed calls may use a previously borrowed descriptor only while that external lifetime claim excludes Ensure, Release, and finalization. Finalize releases both descriptors.
Try_Signal_Borrowed
function Try_Signal_Borrowed (Descriptor : Interfaces.C.int) return Signal_Attempt_Result
Attempt exactly one nonblocking borrowed-descriptor signal. EAGAIN is a coalesced success, EINTR is reported for an outside-lock retry, and all other invalid or failed writes are reported without raising. Unlike Signal_Borrowed, this operation performs exactly one O_NONBLOCK one-byte syscall with no retry, allocation, callback, or retained state, so it may form one bounded protected cut. Retry Signal_Interrupted only after leaving that protected action.
Parameters
- Descriptor
Borrowed live write descriptor
Return value
Result of the single syscall attempt