Description
Provides growable open-addressed maps from immutable fixed-layout keys to immutable fixed-layout values. The fixed map header stores an arena incarnation, current table geometry, and generation-stamped allocation handles. Linear probing uses cached native addresses only for the duration of one checked process-local allocation view. Insertion grows and rehashes before publishing a replacement table. One persisted nonblocking map guard serializes operations across mappings; arena contention is reported in the insertion result. Initialization, destruction, backing-lifetime changes, and concurrent use of one local view require exclusion. Attachment acquires the persisted map guard without waiting while it validates a stable table generation, so another local view may attach while ordinary operations continue.
Arena_Provider
with package Arena_Provider is new Flyology.Data_Structures.Arenas (<>);
Attach
procedure Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Arena : Arena_Provider.View;
Initial_Capacity : Positive)
Attach to a map, acquiring its shared guard without waiting while validating the complete probe table and any deferred allocation handle. This may race operations through other views; exclude concurrent use of Item itself.
Parameters
- Item
View attached on success
- Region
Region containing the fixed map header
- Location
Stored map-header offset
- Arena
Expected attached arena and incarnation
- Initial_Capacity
Expected first table capacity
Raised exceptions
- Layout_Error
Configuration or table contents are corrupt
- Busy_Error
The map guard is active or abandoned
Capacity
function Capacity (Item : View) return Natural
Return the current table capacity.
Parameters
- Item
Internally synchronized map view
Return value
Current power-of-two slot capacity, initially zero
Clear
procedure Clear (Item : in out View; Arena : Arena_Provider.View)
Reset every current slot to empty without releasing table capacity.
Parameters
- Item
Internally synchronized map view
- Arena
Matching attached arena view
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Arena : Arena_Provider.View;
Initial_Capacity : Positive;
Result : out Open_Result)
Initialize virgin bytes or attach to an exact compatible map. Initial capacity, key/value contracts, and arena identity/incarnation must match.
Parameters
- Item
Attached view or detached view during another initialization
- Region
Region containing the fixed map header
- Location
Stored map-header offset
- Arena
Expected attached arena
- Initial_Capacity
Expected first table capacity
- Result
Creation, attachment, or in-progress outcome
Raised exceptions
- Busy_Error
A ready map's guard is active or abandoned
Destroy
procedure Destroy (Item : in out View; Arena : in out Arena_Provider.View)
Release current and deferred tables, destroy the quiescent header, and detach Item.
Parameters
- Item
Exclusively synchronized map view
- Arena
Matching attached arena view
Detach
procedure Detach (Item : in out View)
Detach Item without changing its header or allocations.
Parameters
- Item
Local view to detach
Element
with package Element is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Get
procedure Get
(Item : View;
Arena : Arena_Provider.View;
Key_Data : Key.Source;
Value : out Element.Observed;
Found : out Boolean)
Look up Key and copy its value when present.
Parameters
- Item
Internally synchronized map view
- Arena
Matching attached arena view
- Key_Data
Application key value
- Value
Observation assigned only when Found is true
- Found
True only when Key is present
Identity
Identity : constant Layout_Identity := (Magic => Magic, Version => Layout_Version, Schema => Schema);
Complete stable layout identity for envelopes and tooling.
Initialize
procedure Initialize
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Arena : Arena_Provider.View;
Initial_Capacity : Positive)
Destructively initialize an empty map bound to Arena_Provider.
Parameters
- Item
View attached on success
- Region
Region containing the fixed map header
- Location
Nonzero eight-byte-aligned map-header offset
- Arena
Attached arena used for table allocations
- Initial_Capacity
Power-of-two first table capacity, at least two
Is_Attached
function Is_Attached (Item : View) return Boolean
Report whether Item retains local mapping information.
Parameters
- Item
View to inspect
Return value
True while the local header view is attached
Is_Poisoned
function Is_Poisoned (Item : View) return Boolean
Report whether the map lifecycle is poisoned.
Parameters
- Item
Attached map view
Return value
True only for a persisted poisoned lifecycle
Key
with package Key is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 3;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the occupied entry count.
Parameters
- Item
Internally synchronized map view
Return value
Number of keys currently present
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_4448_4D41_3031#;
Eight-byte magic stored in every dynamic-map header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a quiescent or abandoned-locked map after external recovery authority establishes owner death and quiescence.
Parameters
- Region
Region containing the fixed map header
- Location
Stored map-header offset
Put
procedure Put
(Item : in out View;
Arena : in out Arena_Provider.View;
Key_Data : Key.Source;
Value : Element.Source;
Result : out Put_Result)
Insert Key and Value or replace an existing value. New keys trigger growth before the table exceeds three-quarters occupancy.
Parameters
- Item
Internally synchronized map view
- Arena
Matching attached arena view
- Key_Data
Application key value
- Value
Application mapped value
- Result
Insert, replacement, exhaustion, or arena contention
Put_Result
type Put_Result is (Put_Inserted, Put_Replaced, Put_Arena_Exhausted, Put_Arena_Contended);
Insertion outcome.
Enumeration literals
- Put_Inserted
A previously absent key was inserted
- Put_Replaced
An existing key's value was replaced
- Put_Arena_Exhausted
No arena block can satisfy table growth
- Put_Arena_Contended
Another caller owns arena metadata
Remove
procedure Remove
(Item : in out View; Arena : Arena_Provider.View; Key_Data : Key.Source; Removed : out Boolean)
Remove Key while retaining a tombstone for probe continuity.
Parameters
- Item
Internally synchronized map view
- Arena
Matching attached arena view
- Key_Data
Application key value
- Removed
True only when Key was present
Required_Storage
function Required_Storage return Byte_Count
Return the fixed outer header extent.
Return value
Complete dynamic-map header bytes
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_4448_4D41_0003#
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)
xor Arena_Provider.Identity.Schema
xor Interfaces.Rotate_Left (Arena_Provider.Identity.Magic, 19)
xor Interfaces.Rotate_Left (Interfaces.Unsigned_64 (Arena_Provider.Identity.Version), 41);
Schema for the FNV-1a, linear-probe, arena-backed map contract.
View
type View is limited private;
Process-local attached dynamic-map view.