Description
Provides bounded variable-length byte strings in relocatable storage. Values are byte sequences, not text encodings, and never contain hidden Ada metadata. Immediate operations use one process-shared nonblocking guard and raise Busy_Error on contention. Timed overloads yield and retry that guard through one explicit timeout. An exception after a mutation may have begun poisons the stored object; Poison_Error then persists until exclusive reinitialization. Is_Attached, Capacity, and Is_Poisoned inspect only local or lifecycle metadata and do not acquire the payload guard. The application must exclude Attach, Create_Or_Attach, Detach, Initialize, Destroy, and backing-lifetime changes from every use of the same local View. Separate attached views may perform ordinary operations concurrently.
Append
procedure Append (Item : in out View; Data : Ada.Streams.Stream_Element_Array)
Append Data to the current string. Overlap between Data and the stored payload is supported.
Parameters
- Item
Internally synchronized attached view
- Data
Bytes appended in order
Raised exceptions
- Constraint_Error
The resulting length exceeds Capacity
Append
procedure Append (Item : in out View; Data : Ada.Streams.Stream_Element_Array; Timeout : Wait_Timeout)
Append Data after waiting for the shared guard.
Parameters
- Item
Internally synchronized attached view
- Data
Bytes appended in order; payload overlap is supported
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
- Constraint_Error
The resulting length exceeds Capacity
Assign
procedure Assign (Item : in out View; Data : Ada.Streams.Stream_Element_Array)
Replace the string with Data. Overlap between Data and the stored payload is supported.
Parameters
- Item
Internally synchronized attached view
- Data
Replacement bytes
Raised exceptions
- Constraint_Error
Data exceeds Capacity
Assign
procedure Assign (Item : in out View; Data : Ada.Streams.Stream_Element_Array; Timeout : Wait_Timeout)
Replace the string after waiting for the shared guard.
Parameters
- Item
Internally synchronized attached view
- Data
Replacement bytes; payload overlap is supported
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
- Constraint_Error
Data exceeds Capacity
Attach
procedure Attach
(Item : out View; Region : Region_View; Location : Region_Offset; Maximum_Length : Positive)
Attach to an existing string and validate its immutable identity, extent, and capacity. Attachment may overlap synchronized string operations; the mutable guard and length are validated under the guard by each operation before payload access.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored string offset
- Maximum_Length
Expected payload capacity
Raised exceptions
- Layout_Error
Immutable header or capacity is corrupt
Capacity
function Capacity (Item : View) return Natural
Return the fixed payload capacity.
Parameters
- Item
Attached view
Return value
Maximum retained byte count
Clear
procedure Clear (Item : in out View)
Set the current length to zero without rewriting retained payload bytes.
Parameters
- Item
Internally synchronized attached view
Clear
procedure Clear (Item : in out View; Timeout : Wait_Timeout)
Clear the string after waiting for the shared guard.
Parameters
- Item
Internally synchronized attached 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;
Maximum_Length : Positive;
Result : out Open_Result)
Atomically initialize a known-virgin zeroed extent or attach to a ready compatible string. Only the exact zero lifecycle sentinel is eligible for creation; incomplete, destroyed, corrupt, or incompatible bytes are never overwritten. The operation does not wait for another initializer. Concurrent calls are permitted while the allocation protocol guarantees virgin bytes or the published string is ready.
Parameters
- Item
Attached view, or detached when initialization is in progress
- Region
Independently attached backing region
- Location
Stored string offset
- Maximum_Length
Expected payload capacity
- Result
Whether this caller initialized, attached, or observed an initialization in progress
Destroy
procedure Destroy (Item : in out View)
Invalidate a quiescent string and detach Item.
Parameters
- Item
Internally synchronized attached view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying the string.
Parameters
- Item
View to detach
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; Maximum_Length : Positive)
Initialize an empty string and attach Item. Exclusive reinitialization is the only recovery from a poisoned lifecycle state and makes every preexisting view stale; each peer must attach again.
Parameters
- Item
View attached on success
- Region
Attached backing region
- Location
Nonzero eight-byte-aligned stored offset
- Maximum_Length
Fixed payload capacity
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 an attached string requires reinitialization.
Parameters
- Item
Attached view
Return value
True only when the persisted lifecycle state is poisoned
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 3;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the current retained length.
Parameters
- Item
Attached synchronized view
Return value
Number of initialized payload bytes
Length
function Length (Item : View; Timeout : Wait_Timeout) return Natural
Return the retained length after waiting for the shared guard. The caller yields between attempts and one monotonic deadline spans them.
Parameters
- Item
Attached synchronized view
- Timeout
Maximum wait; zero permits one immediate attempt
Return value
Number of initialized payload bytes
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5342_5354_3031#;
Eight-byte magic stored in every byte-string header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Mark a quiescent string poisoned. Before calling, the application must independently establish that no operation is active, including that a process or task which left the guard locked has terminated. Flyology performs no owner-death detection.
Parameters
- Region
Attached backing region
- Location
Stored string offset
Raised exceptions
- Layout_Error
The stored identity or lifecycle is invalid
- Busy_Error
The lifecycle changed during the poison attempt
Read
procedure Read (Item : View; Data : out Ada.Streams.Stream_Element_Array)
Copy the current string into Data, whose length must equal Length.
Parameters
- Item
Internally synchronized attached view
- Data
Exact-size destination
Raised exceptions
- Constraint_Error
Data has the wrong length
Read
procedure Read (Item : View; Data : out Ada.Streams.Stream_Element_Array; Timeout : Wait_Timeout)
Copy the string after waiting for the shared guard.
Parameters
- Item
Internally synchronized attached view
- Data
Exact-size destination
- Timeout
Maximum wait; zero permits one immediate attempt
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
- Constraint_Error
Data has the wrong length
Required_Storage
function Required_Storage (Maximum_Length : Positive) return Byte_Count
Compute storage for a string with Maximum_Length payload bytes.
Parameters
- Maximum_Length
Maximum retained byte count
Return value
Required header and payload bytes
Schema
Schema : constant Interfaces.Unsigned_64 := 16#0001_4253_5452_0003#;
Schema identifier for the current byte-string layout.
View
type View is limited private;
Process-local attached view.