Description
Provides a bounded multi-producer/multi-consumer ring of immutable fixed-layout elements. Element creation and observation are bound once by the generic adapter. Per-slot sequence counters and acquire/release/CAS operations permit concurrent native tasks or processes to use distinct mappings. Try operations perform at most Contention_Limit claims and never wait on a tasking primitive or syscall; Contended is a bounded failure outcome. Timed Push and Pop yield between bounded claim campaigns until success or one explicit timeout. A participant that terminates after claiming a slot but before publishing it can prevent later progress. Core does not detect participant death; an external recovery authority may poison the ring and reinitialize it after establishing quiescence. Attachment validates immutable identity and geometry and may run while other attached views transfer elements; destruction still requires quiescence and deeply validates mutable state. Signed modular sequence ordering assumes that no paused operation is overtaken by 2**63 completed claims; ordinary 64-bit counter wrap remains supported within that horizon. 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 an existing MPMC ring and validate its published immutable identity, configuration, and complete extent. Other views may transfer elements concurrently; mutable positions and slot sequences therefore receive their deep validation only during quiescent destruction.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored ring offset
- Capacity
Expected power-of-two element count
Raised exceptions
- Layout_Error
Header or geometry is corrupt or incompatible
Contention_Limit
Contention_Limit : constant Positive := 64;
Maximum compare/exchange claim attempts in one operation.
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 while the allocation protocol guarantees virgin bytes or the existing ring is ready. A ready ring may be active.
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
Destroy
procedure Destroy (Item : in out View)
Invalidate an empty, quiescent ring and detach Item.
Parameters
- Item
Exclusively synchronized view
Raised exceptions
- Program_Error
The ring is not empty
Detach
procedure Detach (Item : in out View)
Detach Item without modifying the ring.
Parameters
- Item
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 an empty MPMC ring and attach Item. 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 usable element count
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_4D50_4D43_3031#;
Eight-byte magic stored in every MPMC header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a ring after independently establishing that every participant is dead or quiescent. This is the fail-closed response to an abandoned slot claim; exclusive reinitialization is the recovery operation.
Parameters
- Region
Attached backing region
- Location
Stored ring offset
Pop
procedure Pop (Item : in out View; Data : out Element.Observed; Timeout : Wait_Timeout)
Wait through empty or contended observations until one element is consumed or the monotonic timeout expires.
Parameters
- Item
Any concurrently attached consumer view
- Data
Observation assigned only on success
- Timeout
Maximum wait; zero permits one bounded claim campaign
Raised exceptions
- Timeout_Error
No element is consumed by the deadline
Pop_Result
type Pop_Result is (Popped, Empty, Pop_Contended);
Consumer outcome.
Enumeration literals
- Popped
One element was claimed and consumed
- Empty
No published element was available
- Pop_Contended
The bounded claim-attempt budget was exhausted
Push
procedure Push (Item : in out View; Data : Element.Source; Timeout : Wait_Timeout)
Wait through full or contended observations until Data is published or the monotonic timeout expires. The caller yields between campaigns.
Parameters
- Item
Any concurrently attached producer view
- Data
Application value accepted by the bound creator
- Timeout
Maximum wait; zero permits one bounded claim campaign
Raised exceptions
- Timeout_Error
No element is published by the deadline
Push_Result
type Push_Result is (Pushed, Full, Push_Contended);
Producer outcome.
Enumeration literals
- Pushed
The element was claimed and published
- Full
Every usable slot was occupied
- Push_Contended
The bounded claim-attempt budget was exhausted
Required_Storage
function Required_Storage (Capacity : Positive) return Byte_Count
Compute the complete MPMC layout extent. Capacity must be a power of two and at least two so ready and free slot sequences remain distinct.
Parameters
- Capacity
Number of usable elements
Return value
Required header, sequence counters, padding, and payload bytes
Raised exceptions
- Constraint_Error
Capacity is below two, not a power of two, or cannot be represented in the stored layout
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_4D50_4D43_0004#
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32);
Schema identifier for the current per-slot-sequence algorithm.
Try_Pop
procedure Try_Pop (Item : in out View; Data : out Element.Observed; Result : out Pop_Result)
Attempt to claim and consume the oldest published element.
Parameters
- Item
Any concurrently attached consumer view
- Data
Observation assigned only after a successful claim
- Result
Consumed, empty, or bounded-contention outcome
Try_Push
procedure Try_Push (Item : in out View; Data : Element.Source; Result : out Push_Result)
Attempt to claim and publish Data.
Parameters
- Item
Any concurrently attached producer view
- Data
Application value accepted by the bound creator
- Result
Published, full, or bounded-contention outcome
View
type View is limited private;
Process-local attached MPMC view.