Description
Adds an optional application-level contract around one relocatable object. Leaf structures always retain their own mandatory magic/version/schema; this envelope additionally checks the consumer's chosen contract identity and version before it computes the nested location. Initialization marks the nested leaf incomplete, but the envelope does not otherwise initialize, synchronize, or manage that object, and direct leaf use opts out. Attach, Create_Or_Attach, Detach, Initialize, Destroy, and backing-lifetime changes require exclusion from every use of the same local View.
Attach
procedure Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Content_Extent : Byte_Count;
Content_Alignment : Byte_Count := 8)
Attach only when the application contract, nested leaf identity, nested extent, and alignment all match this generic instance.
Parameters
- Item
Envelope view attached on success
- Region
Independently attached backing region
- Location
Stored envelope offset
- Content_Extent
Expected complete nested structure extent, including at least the shared 64-byte leaf header
- Content_Alignment
Expected nested alignment
Raised exceptions
- Layout_Error
Contract or geometry does not match
Content_Extent
function Content_Extent (Item : View) return Byte_Count
Return the validated nested structure extent.
Parameters
- Item
Attached envelope view
Return value
Complete nested extent in bytes
Content_Location
function Content_Location (Item : View) return Region_Offset
Return the validated stored offset at which the nested leaf begins. No native address is exposed.
Parameters
- Item
Attached envelope view
Return value
Nonzero nested structure offset
Contract_Signature
Contract_Signature : Interfaces.Unsigned_64;
Contract_Version
Contract_Version : Interfaces.Unsigned_64;
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Content_Extent : Byte_Count;
Content_Alignment : Byte_Count;
Result : out Open_Result)
Atomically initialize a known-virgin zeroed extent or attach to a ready compatible envelope. Only the exact zero lifecycle sentinel is eligible for creation; no existing lifecycle is reinitialized. A newly created envelope still leaves its nested leaf incomplete for the caller to initialize. The operation does not wait for another initializer. Concurrent calls are permitted only while the allocation protocol guarantees virgin bytes; if Ready may exist, Attach quiescence applies.
Parameters
- Item
Attached view, or detached when initialization is in progress
- Region
Independently attached backing region
- Location
Stored envelope offset
- Content_Extent
Expected complete nested structure extent
- Content_Alignment
Expected nested alignment
- Result
Whether this caller initialized, attached, or observed an initialization in progress
Destroy
procedure Destroy (Item : in out View)
Invalidate the envelope after the application has quiesced and destroyed or otherwise retired the nested object.
Parameters
- Item
Exclusively synchronized envelope view
Detach
procedure Detach (Item : in out View)
Detach Item without modifying the envelope or nested object.
Parameters
- Item
Local envelope view to detach
Identity
Identity : constant Layout_Identity := (Magic => Magic, Version => Layout_Version, Schema => Schema);
Complete stable identity of the envelope layout itself.
Initialize
procedure Initialize
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Content_Extent : Byte_Count;
Content_Alignment : Byte_Count := 8)
Initialize a contract envelope, atomically mark the nested leaf state incomplete, and then publish the envelope. The caller then initializes the nested leaf at Content_Location. A crash between those steps leaves the nested leaf incomplete even when this extent previously contained a ready leaf, so the leaf's own attachment rejects it. Reinitialization also makes every preexisting envelope view stale.
Parameters
- Item
Envelope view attached on success
- Region
Attached backing region
- Location
Nonzero offset aligned for Content_Alignment
- Content_Extent
Complete nested structure extent, including at least the shared 64-byte leaf header
- Content_Alignment
Required power-of-two nested alignment
Raised exceptions
- Constraint_Error
Generic identity or geometry is invalid
Is_Attached
function Is_Attached (Item : View) return Boolean
Report whether Item is locally attached.
Parameters
- Item
Envelope view to inspect
Return value
True while local mapping information is retained; this does not guarantee the cached initialization epoch is still current
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 2;
Leaf-specific stored-layout version.
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5345_4E56_3031#;
Eight-byte magic stored in every contract envelope.
Nested_Identity
Nested_Identity : Layout_Identity;
Required_Storage
function Required_Storage
(Content_Extent : Byte_Count; Content_Alignment : Byte_Count := 8) return Byte_Count
Compute the envelope plus aligned nested extent.
Parameters
- Content_Extent
Complete nested structure extent, including at least the shared 64-byte leaf header
- Content_Alignment
Required power-of-two nested alignment
Return value
Complete envelope and nested byte extent
Schema
Schema : constant Interfaces.Unsigned_64 := 16#0001_454E_564C_0002#;
Schema identifier for the current envelope geometry.
View
type View is limited private;
Process-local attached envelope view.