Description
Provides growable byte sequences backed by relocatable arena allocations. The fixed header stores only scalar metadata and generation-stamped arena handles. Assign and append allocate a replacement block before publishing it, and memmove-compatible copying supports overlapping Ada byte sources. One persisted nonblocking guard serializes ordinary operations across mappings; arena contention is reported through Growth_Result. Lifecycle operations and detachment of one local View require application exclusion.
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 string and validate its arena allocations.
Parameters
- Item
View attached on success
- Region
Region containing the fixed string header
- Location
Stored string-header offset
- Arena
Expected attached arena and incarnation
- Initial_Capacity
Expected first-growth capacity
Raised exceptions
- Layout_Error
Configuration or mutable state is incompatible
- Busy_Error
The string guard is active or abandoned
Capacity
function Capacity (Item : View) return Natural
Return the currently allocated byte capacity.
Parameters
- Item
Internally synchronized string view
Return value
Current byte capacity, initially zero
Clear
procedure Clear (Item : in out View)
Set Length to zero without releasing retained payload capacity.
Parameters
- Item
Internally synchronized string 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 string. Initial capacity and arena identity/incarnation must match.
Parameters
- Item
Attached view or detached view during another initialization
- Region
Region containing the fixed string header
- Location
Stored string-header offset
- Arena
Expected attached arena
- Initial_Capacity
Expected first-growth byte 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.
Parameters
- Item
Exclusively synchronized string view
- Arena
Matching attached arena view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying its header or allocations.
Parameters
- Item
Local view to detach
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 byte string for Arena_Provider.
Parameters
- Item
View attached on success
- Region
Region containing the fixed string header
- Location
Nonzero eight-byte-aligned string-header offset
- Arena
Attached arena used for payload growth
- Initial_Capacity
First byte 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 string lifecycle is poisoned.
Parameters
- Item
Attached string view
Return value
True only for a persisted poisoned lifecycle
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 2;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the current retained byte count.
Parameters
- Item
Internally synchronized string view
Return value
Current byte length
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_4442_5354_3031#;
Eight-byte magic stored in every dynamic byte-string header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a quiescent or abandoned-locked string after external recovery authority establishes owner death and quiescence.
Parameters
- Region
Region containing the fixed string header
- Location
Stored string-header offset
Read
procedure Read (Item : View; Arena : Arena_Provider.View; Data : out Ada.Streams.Stream_Element_Array)
Copy the complete value into an exact-length destination.
Parameters
- Item
Internally synchronized string view
- Arena
Matching attached arena view
- Data
Destination whose length must equal Length
Required_Storage
function Required_Storage return Byte_Count
Return the fixed header extent; payload is allocated from an arena.
Return value
Complete dynamic byte-string header bytes
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_4442_5354_0002#
xor Arena_Provider.Identity.Schema
xor Interfaces.Rotate_Left (Arena_Provider.Identity.Magic, 19)
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Arena_Provider.Identity.Version), 32);
Schema identifier for the arena-backed byte-string growth contract.
Try_Append
procedure Try_Append
(Item : in out View;
Arena : in out Arena_Provider.View;
Data : Ada.Streams.Stream_Element_Array;
Result : out Growth_Result)
Append Data, growing through Arena when required.
Parameters
- Item
Internally synchronized string view
- Arena
Matching attached arena view
- Data
Bytes appended in order
- Result
Completion, arena exhaustion, or arena contention
Try_Assign
procedure Try_Assign
(Item : in out View;
Arena : in out Arena_Provider.View;
Data : Ada.Streams.Stream_Element_Array;
Result : out Growth_Result)
Replace the string, growing through Arena when required.
Parameters
- Item
Internally synchronized string view
- Arena
Matching attached arena view
- Data
Replacement bytes
- Result
Completion, arena exhaustion, or arena contention
View
type View is limited private;
Process-local attached dynamic byte-string view.