Description
Provides bounded open-addressed maps between immutable fixed-layout keys and values. Their creation and observation contracts are bound once by generic adapters. Capacity is a power of two and probing is linear over cached fixed-stride entries. Stored data contains only state scalars, hashes, keys, and values. Ordinary operations are internally serialized across mappings by one process-capable stored guard. Immediate operations make one acquisition attempt and raise Busy_Error; timed overloads yield and retry through one explicit timeout. Initialization, destruction, and backing-lifetime changes require whole-object quiescence. Attach and ready-object Create_Or_Attach acquire the stored guard while validating mutable contents. The application must exclude Detach, Initialize, Destroy, and backing-lifetime changes from every use of the same local View. Separate views may attach or perform ordinary operations concurrently.
Attach
procedure Attach (Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Attach to a map, acquiring its shared guard without waiting while validating expected geometry, entry states and count, fixed-key hashes, linear-probe reachability, and key uniqueness. This may race operations through other views; exclude concurrent use of Item itself.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored map offset
- Capacity
Expected power-of-two capacity
Raised exceptions
- Layout_Error
Header, geometry, or entries are corrupt
- Busy_Error
The map guard is active or abandoned
- Poison_Error
The map is poisoned
Clear
procedure Clear (Item : in out View)
Reset every entry to empty and set Length to zero.
Parameters
- Item
Attached map view
Raised exceptions
- Busy_Error
Another operation owns the guard
- Poison_Error
The map is poisoned
Clear
procedure Clear (Item : in out View; Timeout : Wait_Timeout)
Clear the map after waiting for the shared guard.
Parameters
- Item
Attached map view
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
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 map. Only the exact zero lifecycle sentinel is eligible for creation; no existing lifecycle is reinitialized. The operation does not wait for another initializer or for the map guard. Concurrent calls may race on allocation-certified virgin bytes or on a ready map; ready attachment acquires the shared guard without waiting.
Parameters
- Item
Attached view, or detached when initialization is in progress
- Region
Independently attached backing region
- Location
Stored map offset
- Capacity
Expected power-of-two capacity
- Result
Whether this caller initialized, attached, or observed an initialization in progress
Destroy
procedure Destroy (Item : in out View)
Invalidate a quiescent map and detach Item.
Parameters
- Item
Exclusively synchronized map view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying the map.
Parameters
- Item
View to detach
Element
with package Element is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Get
procedure Get
(Item : View;
Key_Data : Key.Source;
Value : out Element.Observed;
Timeout : Wait_Timeout;
Found : out Boolean)
Look up Key after waiting for the shared guard.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Value
Observation assigned only when Found is true
- Timeout
Maximum wait; zero permits one immediate attempt
- Found
True only when Key is present
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Get
procedure Get (Item : View; Key_Data : Key.Source; Value : out Element.Observed; Found : out Boolean)
Look up Key and copy its value when present.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Value
Observation assigned only when Found is true
- Found
True only when Key is present
Raised exceptions
- Busy_Error
Another operation owns the guard
- Poison_Error
The map is poisoned
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 map and attach Item. Every preexisting view becomes stale and must attach again before use.
Parameters
- Item
View attached on success
- Region
Attached backing region
- Location
Nonzero eight-byte-aligned stored offset
- Capacity
Power-of-two maximum entry 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 map was explicitly poisoned.
Parameters
- Item
Attached map view
Return value
True only when the shared lifecycle state is Poisoned
Raised exceptions
- Region_Error
Item is detached
Key
with package Key is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 4;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the current occupied entry count.
Parameters
- Item
Attached view
Return value
Number of keys currently present
Raised exceptions
- Busy_Error
Another operation owns the guard
- Poison_Error
The map is poisoned
Length
function Length (Item : View; Timeout : Wait_Timeout) return Natural
Return Length after waiting for the shared map guard.
Parameters
- Item
Attached map view
- Timeout
Maximum wait; zero permits one immediate attempt
Return value
Number of keys currently present
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5348_4D41_3031#;
Eight-byte magic stored in every map header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a ready or abandoned-locked map after independently establishing that no live owner can still mutate it. This recovery operation validates the map identity without attaching mutable contents. Poisoning is permanent until exclusive reinitialization.
Parameters
- Region
Attached backing region
- Location
Stored map offset
Raised exceptions
- Layout_Error
The location is incomplete or has another identity
- Busy_Error
The lifecycle changed during the poison attempt
Put
procedure Put (Item : in out View; Key_Data : Key.Source; Value : Element.Source; Result : out Put_Result)
Insert Key and Value, or replace the value for an existing key.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Value
Application mapped value
- Result
Insert, replacement, or full-table outcome
Raised exceptions
- Busy_Error
Another operation owns the guard
- Poison_Error
The map is poisoned
Put
procedure Put
(Item : in out View;
Key_Data : Key.Source;
Value : Element.Source;
Timeout : Wait_Timeout;
Result : out Put_Result)
Insert or replace after waiting for the shared guard.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Value
Application mapped value
- Timeout
Maximum wait; zero permits one immediate attempt
- Result
Insert, replacement, or full-table outcome
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Put_Result
type Put_Result is (Inserted, Replaced, Table_Full);
Insertion outcome.
Enumeration literals
- Inserted
A previously absent key was inserted
- Replaced
An existing key's value was replaced
- Table_Full
No empty or deleted slot was available
Remove
procedure Remove
(Item : in out View; Key_Data : Key.Source; Timeout : Wait_Timeout; Removed : out Boolean)
Remove Key after waiting for the shared guard.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Timeout
Maximum wait; zero permits one immediate attempt
- Removed
True only when Key was present
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Remove
procedure Remove (Item : in out View; Key_Data : Key.Source; Removed : out Boolean)
Remove Key when present, retaining a tombstone for probe continuity.
Parameters
- Item
Attached map view
- Key_Data
Application key value
- Removed
True only when an occupied entry was deleted
Raised exceptions
- Busy_Error
Another operation owns the guard
- Poison_Error
The map is poisoned
Required_Storage
function Required_Storage (Capacity : Positive) return Byte_Count
Compute the complete map extent. Capacity must be a power of two.
Parameters
- Capacity
Maximum occupied entry count
Return value
Required header, entry metadata, padding, keys, and values
Raised exceptions
- Constraint_Error
Capacity is not a power of two
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_484D_4150_0004#
xor Key.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Key.Version), 32)
xor Interfaces.Rotate_Left (Element.Signature, 17)
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 48);
Schema identifier for the current FNV-1a/open-addressed layout.
View
type View is limited private;
Process-local attached map view.