Description
Provides a fixed-capacity persisted registry of exact names and relocatable extents inside one shared mapping. The registry stores only fixed-width scalars and name bytes. A persisted nonblocking guard serializes lookup, allocation, removal, and reuse across processes and native tasks.
An initializing slot remains unavailable until its creator publishes success or failure. If a creator dies while holding the registry guard or an initialization claim, the state remains abandoned. This package never steals ownership and provides no process-death detection. A live creator can publish failure. Otherwise an independently authorized supervisor must establish owner death and participant quiescence before replacing the whole backing object.
Attach_Region
procedure Attach_Region (Item : View; Region : in out Flyology.Data_Structures.Regions.View)
Attach a Data_Structures region view to the complete borrowed mapping. Detach leaf views, Region, and Item before unmapping Source.
Parameters
- Item
Attached segment view
- Region
Detached relocatable region view to attach
Raised exceptions
- Segment_Error
Item is detached or no longer ready
Claimed_Extent
procedure Claimed_Extent
(Item : View;
Claim : Creation_Claim;
Location : out Flyology.Data_Structures.Region_Offset;
Length : out Byte_Length)
Return the unpublished extent to its creator. Other callers cannot construct a valid Creation_Claim and Resolve rejects initializing slots. A reused extent may retain bytes from its previous generation, so the creator must explicitly initialize the complete nested object before publication rather than assuming virgin zero storage.
Parameters
- Item
Attached segment containing Claim
- Claim
Live creator capability
- Location
Persisted region offset of the unpublished extent
- Length
Reserved extent length
Raised exceptions
- Segment_Error
Claim is invalid, stale, or no longer initializing
Configuration
type Configuration is record
Schema : Interfaces.Unsigned_64;
Registry_Capacity : Positive;
Maximum_Name_Length : Positive;
Allocation_Alignment : Positive := 64;
end record;
Segment registry geometry and application schema. All values are stored and checked exactly at attachment.
Record fields
- Schema
Nonzero application-selected segment contract identity
- Registry_Capacity
Fixed number of named registry slots
- Maximum_Name_Length
Maximum exact UTF-8 or opaque byte name length; names are Ada String bytes and receive no normalization
- Allocation_Alignment
Power-of-two alignment for every named extent and for reuse eligibility
Create_Or_Attach
procedure Create_Or_Attach
(Item : in out View; Source : Mapping; Config : Configuration; Result : out Segment_Open_Result)
Race-safely initialize or attach the segment at mapping offset zero. Only mappings derived from an exclusively created backing object may claim an exact-zero lifecycle sentinel. Opened or received mappings report Initialization_In_Progress instead of repairing abandoned zero bytes. Ready attachments validate magic, version, schema, total extent, capacity, name limit, slot geometry, and allocation alignment.
Parameters
- Item
Detached segment view to populate
- Source
Live mapping borrowed for Item's lifetime
- Config
Exact persisted configuration
- Result
Initialization or attachment outcome
Raised exceptions
- Constraint_Error
Config or mapping extent is invalid
- Segment_Error
Persisted state or configuration is corrupt
Creation_Claim
type Creation_Claim is limited private;
Limited creator capability returned only to the winner of a name race. It grants access to unpublished bytes and the right to publish success or failure. Losing callers receive an invalid claim.
Detach
procedure Detach (Item : in out View)
Detach Item without changing the registry or mapping.
Parameters
- Item
Segment view to detach
Failure_Code
subtype Failure_Code is Interfaces.Unsigned_32 range 1 .. Interfaces.Unsigned_32'Last;
Application-defined nonzero initialization failure code.
Failure_Of
function Failure_Of (Item : View; Handle : Named_Handle) return Failure_Code
Return a failed handle's application code.
Parameters
- Item
Attached segment containing Handle
- Handle
Handle whose state must be Failed
Return value
Published nonzero failure code
Raised exceptions
- Segment_Error
Handle is stale or not failed
Find_Or_Create_Result
type Find_Or_Create_Result is
(Created,
Attached_Existing,
Initialization_In_Progress,
Previous_Initialization_Failed,
Configuration_Mismatch,
Registry_Busy,
Registry_Exhausted,
Segment_Exhausted,
Generation_Exhausted);
Outcome of one nonblocking exact-name find-or-create attempt.
Enumeration literals
- Created
The caller owns the returned Creation_Claim and must publish success or failure
- Attached_Existing
The same exact name has a ready matching extent
- Initialization_In_Progress
The same exact name has an unpublished creator
- Previous_Initialization_Failed
Failure was published and must be explicitly removed before reuse
- Configuration_Mismatch
The exact name exists with another length
- Registry_Busy
The persisted guard was already owned
- Registry_Exhausted
No free or removed registry slot is available
- Segment_Exhausted
No reusable extent fits and bump space is spent
- Generation_Exhausted
The nonwrapping generation counter is spent
Handle_State
type Handle_State is (Null_Handle, Initializing, Ready, Failed, Removed, Stale);
Current state of a generation-stamped named handle.
Enumeration literals
- Null_Handle
The canonical null handle was supplied
- Initializing
The handle names an unpublished creation
- Ready
The handle names a published extent
- Failed
The handle names a published initialization failure
- Removed
The handle's slot was removed but not yet reused
- Stale
The slot generation no longer matches or is invalid
Is_Attached
function Is_Attached (Item : View) return Boolean
Report whether Item borrows a live mapping.
Parameters
- Item
Segment view to inspect
Return value
True after successful creation or attachment
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 1;
Current fixed stored-layout version.
Lookup_Result
type Lookup_Result is (Found, Not_Found, Initialization_In_Progress, Initialization_Failed, Registry_Busy);
Outcome of one nonblocking exact-name lookup.
Enumeration literals
- Found
A ready extent was found
- Not_Found
No active exact name exists
- Initialization_In_Progress
The name exists but is unpublished
- Initialization_Failed
The name has a published failure
- Registry_Busy
The persisted guard was already owned
Named_Handle
type Named_Handle is private;
Copyable fixed-width generation-stamped name handle. It contains no native pointer and must be revalidated against a View before use.
Publish
procedure Publish (Item : View; Claim : in out Creation_Claim)
Publish successful initialization with release ordering and consume the creator capability. The returned Named_Handle then resolves as ready.
Parameters
- Item
Attached segment containing Claim
- Claim
Live creator capability to consume
Raised exceptions
- Segment_Error
Claim is invalid, stale, or no longer initializing
Publish_Failure
procedure Publish_Failure (Item : View; Claim : in out Creation_Claim; Failure : Failure_Code)
Publish explicit initialization failure with release ordering and consume Claim. The failed name remains reserved until Remove succeeds; no caller silently overwrites it.
Parameters
- Item
Attached segment containing Claim
- Claim
Live creator capability to consume
- Failure
Nonzero application failure code
Raised exceptions
- Segment_Error
Claim is invalid, stale, or no longer initializing
Quiescence_Authority
type Quiescence_Authority is (Caller_Established_Quiescence);
Explicit declaration that the caller has stopped every participant from accessing the source registry and all nested objects. This value is not proof: Flyology cannot discover application-owned views, operations, or peer acknowledgments. It makes the required authority visible at the migration call site.
Enumeration literals
- Caller_Established_Quiescence
The application has established complete source-segment quiescence
Remove_Result
type Remove_Result is (Removed, Not_Found, Initialization_In_Progress, Registry_Busy);
Outcome of explicit name removal.
Enumeration literals
- Removed
A ready or failed entry became reusable
- Not_Found
No active exact name exists
- Initialization_In_Progress
A live creation claim prevents removal
- Registry_Busy
The persisted guard was already owned
Replacement_Result
type Replacement_Result is (Replacement_Ready, Registry_Busy, Initialization_In_Progress);
Outcome of preparing a larger replacement mapping.
Enumeration literals
- Replacement_Ready
The target contains a ready compatible clone
- Registry_Busy
A registry operation still owns the source guard
- Initialization_In_Progress
A named extent still has an unpublished creator claim
Required_Registry_Storage
function Required_Registry_Storage (Config : Configuration) return Byte_Length
Return the minimum bytes occupied by the segment header and registry, rounded to Allocation_Alignment. A useful segment must be larger so at least one named extent fits.
Parameters
- Config
Registry geometry to validate
Return value
First allocatable byte offset
Raised exceptions
- Constraint_Error
Configuration is invalid or overflows
Resolve
procedure Resolve
(Item : View;
Handle : Named_Handle;
Location : out Flyology.Data_Structures.Region_Offset;
Length : out Byte_Length)
Resolve a ready generation-stamped handle to a persisted region offset and extent length. Removed, failed, initializing, or reused slots fail. Resolution does not pin the returned bytes against a later Remove; application lifecycle coordination must keep the named extent live while a nested object view borrows it.
Parameters
- Item
Attached segment containing Handle
- Handle
Untrusted generation-stamped handle
- Location
Persisted region offset
- Length
Published extent length
Raised exceptions
- Segment_Error
Handle is null, stale, or not ready
Segment_Error
Segment_Error : exception;
Raised when persisted segment identity, geometry, or state is corrupt.
Segment_Open_Result
type Segment_Open_Result is (Initialized_New, Attached_Existing, Initialization_In_Progress);
Result of race-safe segment creation or attachment.
Enumeration literals
- Initialized_New
This mapping was authorized by exclusive backing creation, claimed the zero lifecycle, and published the registry
- Attached_Existing
A ready compatible registry already existed
- Initialization_In_Progress
Another initializer owns the claim, or this mapping came from an opener and is not allowed to claim zero
State_Of
function State_Of (Item : View; Handle : Named_Handle) return Handle_State
Inspect a handle after validating its slot and generation.
Parameters
- Item
Attached segment containing Handle
- Handle
Handle to inspect
Return value
Current state or Stale
Raised exceptions
- Segment_Error
Persisted slot state is corrupt
Try_Find
procedure Try_Find
(Item : View;
Name : String;
Handle : out Named_Handle;
Result : out Lookup_Result;
Failure : out Interfaces.Unsigned_32)
Attempt exact-name lookup without allocating or changing registry state.
Parameters
- Item
Attached ready segment
- Name
Nonempty exact byte name within the configured limit
- Handle
Generation-stamped handle for the active slot, if any
- Result
Nonblocking lookup outcome
- Failure
Published failure code when Result is Initialization_Failed
Raised exceptions
- Constraint_Error
Name is invalid
- Segment_Error
Persisted registry state is corrupt
Try_Find_Or_Create
procedure Try_Find_Or_Create
(Item : View;
Name : String;
Requested_Length : Byte_Length;
Handle : out Named_Handle;
Claim : out Creation_Claim;
Result : out Find_Or_Create_Result;
Failure : out Interfaces.Unsigned_32)
Attempt exact-name lookup or reserve a new aligned extent. Hashes only accelerate scanning: stored length and every name byte are compared, so collisions never alias names. Removed extents are reused when their stored length is at least Requested_Length; otherwise monotonic bump space is used. A created extent is not exposed through Resolve until Publish succeeds.
Parameters
- Item
Attached ready segment
- Name
Nonempty exact byte name within the configured limit
- Requested_Length
Positive requested extent length
- Handle
Generation-stamped handle for the matching or new slot
- Claim
Valid creator capability only when Result is Created
- Result
Nonblocking operation outcome
- Failure
Published failure code for a previous failed initializer, otherwise zero
Raised exceptions
- Constraint_Error
Name or requested length is invalid
- Segment_Error
Persisted registry state is corrupt
Try_Prepare_Replacement
procedure Try_Prepare_Replacement
(Source : View;
Target : Mapping;
Config : Configuration;
Quiescence : Quiescence_Authority;
Result : out Replacement_Result)
Attempt to prepare a larger replacement segment while preserving every registry slot, exact name, extent offset, generation, allocation frontier, and stored payload byte through the source frontier. Guard contention and an unpublished creation claim return immediately. A successful attempt synchronously zeroes Target and copies through the source frontier while holding the registry guard. That work is linear in the target extent plus the copied frontier, can fault file-backed pages, and may occupy a lightweight task's event-loop pthread. Use a native task boundary unless occupying that pthread is explicitly acceptable.
Target must be a distinct mapping with a virgin lifecycle derived from exclusive backing creation, must be strictly larger than Source, and must use the same persisted Configuration. Anonymous, named POSIX, and file-backed target mappings are all accepted through the common Mapping contract; the caller must keep a named or file target private until publication and cutover are authorized.
The caller must first establish quiescence for every process, native task, registry operation, creation claim, and nested relocatable object. The source registry guard detects a concurrent registry operation, and the slot scan detects an unpublished creation claim, but this operation cannot detect concurrent leaf access. On success it publishes the target lifecycle last; Source remains ready and unchanged. The caller then uses Create_Or_Attach to create a process-local target view. Peer handoff, attachment acknowledgment, cutover, old-view detachment, persistence, and old-backing retirement remain explicit application protocol steps. Registry capacity, name length, alignment, and schema do not grow; only the allocation tail becomes larger.
Parameters
- Source
Attached ready source segment kept alive and unchanged
- Target
Distinct virgin mapping from exclusive backing creation
- Config
Exact source and target registry configuration
- Quiescence
Required caller declaration of complete quiescence
- Result
Ready, busy, or unpublished-claim outcome
Raised exceptions
- Constraint_Error
Target is not strictly larger or geometry is not natively representable
- Validation_Error
Target is unmapped, nonexclusive, nonvirgin, or aliases the source mapping
- Segment_Error
Source identity, geometry, frontier, slot, or lifecycle state is corrupt
Try_Remove
procedure Try_Remove (Item : View; Name : String; Result : out Remove_Result)
Explicitly remove a ready or failed exact name. Initializing entries are never stolen. The slot and extent become candidates for later reuse; existing handles stop resolving, and reuse receives a new generation. Removing registry metadata does not destroy application objects in the extent and does not unlink or close the OS backing object.
Parameters
- Item
Attached segment
- Name
Exact name to remove
- Result
Nonblocking removal outcome
Raised exceptions
- Constraint_Error
Name is invalid
- Segment_Error
Persisted registry state is corrupt
View
type View is limited private;
Process-local segment view borrowing one Mapping. Detach it before the mapping is unmapped. Segment detachment does not change stored bytes.