Description
Provides growable vectors of immutable fixed-layout elements. The vector header remains at one relocatable region offset while payload storage is a generation-stamped arena allocation. Growth allocates and copies before publishing the replacement handle. Operations are serialized across mappings by the vector's persisted nonblocking guard; arena contention is reported separately through Growth_Result. Neither guard spins or waits. Callers must exclude lifecycle operations and local View detachment from ordinary use of that same View, and must keep the supplied arena attached. A vector and its arena may be mapped at different native addresses.
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 quiescent vector and validate its header plus every current or deferred arena allocation handle.
Parameters
- Item
View attached on success
- Region
Region containing the vector header
- Location
Stored vector-header offset
- Arena
Expected attached arena instance and incarnation
- Initial_Capacity
Expected first-growth capacity
Raised exceptions
- Layout_Error
Configuration or mutable state is incompatible
- Busy_Error
The vector guard is active or abandoned
Capacity
function Capacity (Item : View) return Natural
Return the currently allocated element capacity. This operation takes the vector guard because capacity changes during growth.
Parameters
- Item
Internally synchronized vector view
Return value
Current element capacity, initially zero
Clear
procedure Clear (Item : in out View)
Set Length to zero without releasing current payload capacity.
Parameters
- Item
Internally synchronized vector 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 allocation-certified virgin bytes or attach to a compatible ready vector. Initial capacity, element contract, and arena instance identity must exactly match an existing header.
Parameters
- Item
Attached view or detached view during another initialization
- Region
Region containing the fixed vector header
- Location
Stored vector-header offset
- Arena
Expected attached arena instance
- Initial_Capacity
Expected first-growth capacity
- Result
Creation, attachment, or in-progress outcome
Destroy
procedure Destroy (Item : in out View; Arena : in out Arena_Provider.View)
Release current and deferred allocations, destroy the quiescent header, and detach Item. Arena contention raises Busy_Error before an allocation that could not be reclaimed is forgotten.
Parameters
- Item
Exclusively synchronized vector view
- Arena
Matching attached arena view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying its header or arena allocations.
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 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 vector. Existing payload allocations are not inferred or reclaimed from overwritten bytes; the caller must retire dependent views and allocations before recovery initialization.
Parameters
- Item
View attached on success
- Region
Region containing the fixed vector header
- Location
Nonzero eight-byte-aligned vector-header offset
- Arena
Attached arena used for all future payload allocations
- Initial_Capacity
First element capacity requested on growth
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 vector lifecycle is poisoned.
Parameters
- Item
Attached vector view
Return value
True only for a persisted poisoned lifecycle
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 3;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the current initialized element count.
Parameters
- Item
Internally synchronized vector view
Return value
Number of initialized elements
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_4456_4543_3031#;
Eight-byte magic stored in every dynamic-vector header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a ready or abandoned-locked vector after independently proving operation quiescence and owner death where applicable.
Parameters
- Region
Region containing the fixed vector header
- Location
Stored vector-header offset
Read
function Read (Item : View; Arena : Arena_Provider.View; Index : Positive) return Element.Observed
Observe the one-based initialized element at Index.
Parameters
- Item
Internally synchronized vector view
- Arena
Matching attached arena view
- Index
One-based initialized element position
Return value
Bound immutable observation
Replace
procedure Replace
(Item : in out View; Arena : Arena_Provider.View; Index : Positive; Data : Element.Source)
Replace the one-based initialized element at Index.
Parameters
- Item
Internally synchronized vector view
- Arena
Matching attached arena view
- Index
One-based initialized element position
- Data
Application element value
Required_Storage
function Required_Storage return Byte_Count
Return the fixed header extent. Payload bytes are allocated separately from the receiving arena.
Return value
Complete stored dynamic-vector header bytes
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_4456_4543_0003#
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32)
xor Arena_Provider.Identity.Schema
xor Interfaces.Rotate_Left (Arena_Provider.Identity.Magic, 19)
xor Interfaces.Unsigned_64 (Arena_Provider.Identity.Version);
Schema identifier for the arena-backed vector layout and growth policy.
Try_Append
procedure Try_Append
(Item : in out View;
Arena : in out Arena_Provider.View;
Data : Element.Source;
Result : out Growth_Result)
Append one element, growing through Arena when required.
Parameters
- Item
Internally synchronized vector view
- Arena
Matching attached arena view
- Data
Application element value
- Result
Completion, arena exhaustion, or arena contention
Raised exceptions
- Busy_Error
Another caller owns the vector guard
Try_Pop
procedure Try_Pop
(Item : in out View; Arena : Arena_Provider.View; Data : out Element.Observed; Popped : out Boolean)
Copy and remove the last element. Empty vectors return Popped false and do not assign Data or release their retained allocation.
Parameters
- Item
Internally synchronized vector view
- Arena
Matching attached arena view
- Data
Observation assigned only when Popped is true
- Popped
True only when an element was removed
View
type View is limited private;
Process-local attached dynamic-vector view.