Description
Provides bounded vectors of immutable fixed-layout values in relocatable storage. Element creation and observation are selected once by the generic adapter. Append creates independent immutable bytes before acquiring the guard, observation reads a scoped Const_Ref without an intermediate representation copy, and emplacement delays creation until capacity is known to be available. Adapter operations must not block, retain references, reenter this vector, or change its backing lifetime.
Immediate operations make one process-shared guard attempt and raise Busy_Error on contention. Timed overloads yield between attempts. The application must exclude lifecycle operations and local-view detachment from every use of that same View; separate attached views may perform ordinary operations concurrently.
Attach
procedure Attach (Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Attach to a quiescent vector with the expected capacity and immutable element contract.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored vector offset
- Capacity
Expected maximum element count
Raised exceptions
- Layout_Error
Identity, geometry, or length is incompatible
Capacity
function Capacity (Item : View) return Natural
Return the fixed element capacity.
Parameters
- Item
Attached view
Return value
Maximum initialized element count
Clear
procedure Clear (Item : in out View)
Set Length to zero without rewriting immutable payload bytes.
Parameters
- Item
Internally synchronized vector view
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Capacity : Positive;
Result : out Open_Result)
Initialize certified virgin bytes or attach to an exactly compatible vector. Capacity and the generic element identity must match.
Parameters
- Item
Attached view or detached view while initialization proceeds
- Region
Independently attached backing region
- Location
Stored vector offset
- Capacity
Expected maximum element count
- Result
Creation, attachment, or in-progress outcome
Destroy
procedure Destroy (Item : in out View)
Invalidate a quiescent vector and detach Item.
Parameters
- Item
Exclusively synchronized vector view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying stored bytes.
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 envelope instances and tooling.
Initialize
procedure Initialize
(Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Initialize an empty vector and attach Item. Exclusive initialization invalidates every earlier view of the same extent.
Parameters
- Item
View attached on success
- Region
Attached backing region
- Location
Nonzero stored offset aligned for this element type
- Capacity
Maximum element count
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 process-local 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 the persisted poisoned lifecycle
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 4;
Leaf-specific stored-layout version.
Length
function Length (Item : View) return Natural
Return the initialized element count without waiting.
Parameters
- Item
Attached synchronized view
Return value
Current element count
Length
function Length (Item : View; Timeout : Wait_Timeout) return Natural
Return the initialized element count after waiting for the guard.
Parameters
- Item
Attached synchronized view
- Timeout
Maximum wait; zero permits one immediate attempt
Return value
Current element count
Raised exceptions
- Timeout_Error
The guard remains owned through the deadline
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5356_4543_3031#;
Eight-byte magic stored in every vector header.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison a quiescent ready or abandoned-locked vector after external owner-death and quiescence authorization.
Parameters
- Region
Region containing the vector
- Location
Stored vector offset
Read
function Read (Item : View; Index : Positive) return Element.Observed
Observe the indexed element without copying its representation.
Parameters
- Item
Internally synchronized vector view
- Index
One-based initialized element position
Return value
Application observation returned by the bound observer
Raised exceptions
- Constraint_Error
Index is outside the initialized range
Read
function Read (Item : View; Index : Positive; Timeout : Wait_Timeout) return Element.Observed
Observe one element after waiting for the shared guard.
Parameters
- Item
Internally synchronized vector view
- Index
One-based initialized element position
- Timeout
Maximum wait; zero permits one immediate attempt
Return value
Application observation returned by the bound observer
Read_Value
function Read_Value (Item : View; Index : Positive) return Element.Value
Copy the indexed element into an independent immutable representation.
Parameters
- Item
Internally synchronized vector view
- Index
One-based initialized element position
Return value
Independent immutable value
Replace
procedure Replace (Item : in out View; Index : Positive; Data : Element.Source)
Replace one element with another immutable value. No mutable reference to the published element is exposed.
Parameters
- Item
Internally synchronized vector view
- Index
One-based initialized element position
- Data
Application value accepted by the element adapter
Replace
procedure Replace (Item : in out View; Index : Positive; Data : Element.Source; Timeout : Wait_Timeout)
Replace after waiting for the shared guard.
Parameters
- Item
Internally synchronized vector view
- Index
One-based initialized element position
- Data
Application value accepted by the element adapter
- Timeout
Maximum wait; zero permits one immediate attempt
Required_Storage
function Required_Storage (Capacity : Positive) return Byte_Count
Compute the complete fixed-capacity vector extent.
Parameters
- Capacity
Maximum element count
Return value
Required header, padding, and immutable element bytes
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_5645_4354_0004#
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32);
Schema identifier composed with the immutable element identity.
Try_Append
procedure Try_Append
(Item : in out View; Data : Element.Source; Timeout : Wait_Timeout; Appended : out Boolean)
Append after waiting for the shared guard.
Parameters
- Item
Internally synchronized vector view
- Data
Application value accepted by the element adapter
- Timeout
Maximum wait; zero permits one immediate attempt
- Appended
True only when capacity was available
Try_Append
procedure Try_Append (Item : in out View; Data : Element.Source; Appended : out Boolean)
Create and append an immutable value. Creation completes before guard acquisition, so a raising creator cannot mutate shared storage.
Parameters
- Item
Internally synchronized vector view
- Data
Application value accepted by the element adapter
- Appended
True only when capacity was available
Try_Emplace
procedure Try_Emplace (Item : in out View; Data : Element.Source; Appended : out Boolean)
Create an immutable value only after finding an unpublished tail slot. The bound creator is not called when the vector is full.
Parameters
- Item
Internally synchronized vector view
- Data
Application value accepted by the bound creator
- Appended
True only when creation completed and was published
Try_Pop
procedure Try_Pop (Item : in out View; Data : out Element.Observed; Popped : out Boolean)
Observe and remove the last element without copying its representation. The bound observer is not called for an empty vector; a raising observer leaves the element live.
Parameters
- Item
Internally synchronized vector view
- Data
Observation assigned only when an element is consumed
- Popped
True only when observation returned and length decremented
View
type View is limited private;
Process-local attached vector view.