Description
Provides a bounded single-producer/single-consumer ring of immutable fixed-layout elements. Creation and observation are bound once by the generic element adapter. Exactly one producer may call Try_Push and exactly one consumer may call Try_Pop at a time; they may be native tasks or processes using different mappings. Acquire/release publication makes payload transfer explicit. Attachment and destruction require quiescence. Try operations never wait; timed Push and Pop yield without invoking a blocking syscall. Attach, Create_Or_Attach, Detach, Initialize, Destroy, and backing-lifetime changes must not race with any use of the same local View.
Attach
procedure Attach (Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Attach to a quiescent initialized ring and validate configuration and producer/consumer indices.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored ring offset
- Capacity
Expected usable element count
Raised exceptions
- Layout_Error
Header, configuration, or indices are corrupt
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Capacity : Positive;
Result : out Open_Result)
Atomically initialize a known-virgin zeroed extent or attach to a ready compatible ring. Only the exact zero lifecycle sentinel is eligible for creation; no existing lifecycle is reinitialized. The operation does not wait for another initializer. Concurrent calls are permitted only while the allocation protocol guarantees virgin bytes; if Ready may exist, Attach quiescence applies.
Parameters
- Item
Attached view, or detached when initialization is in progress
- Region
Independently attached backing region
- Location
Stored ring offset
- Capacity
Expected power-of-two usable element count
- Result
Whether this caller initialized, attached, or observed an initialization in progress
Current_Metadata
function Current_Metadata (Item : View) return Metadata
Return immutable validated configuration.
Parameters
- Item
Attached ring view
Return value
Capacity, element size, and stored extent
Destroy
procedure Destroy (Item : in out View)
Invalidate an empty, quiescent ring and detach Item.
Parameters
- Item
Exclusively synchronized ring view
Raised exceptions
- Program_Error
The ring is not empty
Detach
procedure Detach (Item : in out View)
Detach Item without changing the ring.
Parameters
- Item
Local view to detach
Element
with package Element is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Identity
Identity : constant Layout_Identity := (Magic => Magic, Version => Layout_Version, Schema => Schema);
Complete stable layout identity for envelope instances and tooling.
Initialize
procedure Initialize
(Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Initialize a new empty ring and attach Item. The caller exclusively owns the target extent until ready-state publication completes. Every preexisting view becomes stale and must attach again.
Parameters
- Item
View attached on success
- Region
Attached backing region
- Location
Nonzero eight-byte-aligned stored offset
- Capacity
Power-of-two number of usable elements
Is_Attached
function Is_Attached (Item : View) return Boolean
Report whether Item is locally attached.
Parameters
- Item
View to inspect
Return value
True while local mapping information is retained; this does not guarantee the cached initialization epoch is still current
Is_Poisoned
function Is_Poisoned (Item : View) return Boolean
Report whether Item's backing ring was explicitly poisoned.
Parameters
- Item
Attached ring view
Return value
True only when the shared lifecycle state is Poisoned
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 4;
Leaf-specific stored-layout version.
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5350_5343_3031#;
Eight-byte magic stored in every SPSC header.
Metadata
type Metadata is record
Capacity : Interfaces.Unsigned_32;
Element_Size : Interfaces.Unsigned_32;
Element_Alignment : Interfaces.Unsigned_32;
Extent : Byte_Count;
end record;
Immutable validated SPSC configuration.
Record fields
- Capacity
Number of usable elements
- Element_Size
Bytes in the bound immutable element
- Element_Alignment
Required element alignment
- Extent
Complete stored layout size
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a ready ring after independently establishing that its producer and consumer are dead or quiescent. Operations and attachment then fail closed until exclusive reinitialization.
Parameters
- Region
Attached backing region
- Location
Stored ring offset
Pop
procedure Pop (Item : in out View; Data : out Element.Observed; Timeout : Wait_Timeout)
Wait until one element is consumed or the monotonic timeout expires. The sole consumer yields between empty-ring observations.
Parameters
- Item
Consumer's attached view
- Data
Observation assigned only on success
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The ring remains empty through the deadline
Push
procedure Push (Item : in out View; Data : Element.Source; Timeout : Wait_Timeout)
Wait until Data is published or the monotonic timeout expires. The sole producer yields between full-ring observations.
Parameters
- Item
Producer's attached view
- Data
Application value accepted by the bound creator
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The ring remains full through the deadline
Required_Storage
function Required_Storage (Capacity : Positive) return Byte_Count
Compute the complete SPSC layout extent. Capacity must be a power of two so hot-path slot selection uses a mask.
Parameters
- Capacity
Power-of-two number of usable elements
Return value
Required header, padding, and payload bytes
Raised exceptions
- Constraint_Error
Capacity or arithmetic is invalid
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_5350_5343_0004#
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32);
Schema identifier for the current SPSC layout and memory ordering.
Try_Pop
procedure Try_Pop (Item : in out View; Data : out Element.Observed; Popped : out Boolean)
Acquire and observe the next element. The sole consumer calls this operation. An empty ring returns immediately with Popped false and does not assign Data.
Parameters
- Item
Consumer's attached view
- Data
Observation assigned only on success
- Popped
True only when an element was consumed
Raised exceptions
- Layout_Error
Stored indices are corrupt
Try_Push
procedure Try_Push (Item : in out View; Data : Element.Source; Pushed : out Boolean)
Create Data in the next unpublished element and publish it with a release store. The sole producer calls this operation. A full ring returns immediately with Pushed false and leaves Data untouched.
Parameters
- Item
Producer's attached view
- Data
Application value accepted by the bound creator
- Pushed
True only when the element was published
Raised exceptions
- Layout_Error
Stored indices are corrupt
View
type View is limited private;
Process-local attached ring view.