Flyology API reference

Description

Provides a fixed caller-owned relocatable allocation domain using one statically selected allocation algorithm. Instantiation introduces no runtime dispatch or stored callback. Algorithm identity and configuration are validated by Create_Or_Attach and Attach. The selected algorithm owns allocation synchronization, abandonment, poison, and recovery semantics.

Algorithm

with package Algorithm is new Flyology.Data_Structures.Allocation_Algorithms.Contract (<>);

Allocated

Allocated : constant Allocation_Result := Allocation_Algorithms.Allocated;

A newly allocated block was returned.

Allocation_Contended

Allocation_Contended : constant Allocation_Result := Allocation_Algorithms.Allocation_Contended;

Another caller owns allocator metadata.

Allocation_Handle

subtype Allocation_Handle is Allocation_Algorithms.Allocation_Handle;

Fixed-width address-independent allocation identity.

Allocation_Result

subtype Allocation_Result is Allocation_Algorithms.Allocation_Result;

Allocation attempt outcome.

Attach

procedure Attach
  (Item          : out Algorithm.View;
   Region        : Region_View;
   Location      : Region_Offset;
   Configuration : Algorithm.Configuration;
   Instance_ID   : Interfaces.Unsigned_64)

Attach to a quiescent compatible arena and validate its complete stored algorithm state.

Parameters

Item: View attached on success
Region: Independently attached backing region
Location: Stored arena offset
Configuration: Expected algorithm-specific geometry
Instance_ID: Expected arena identity

Raised exceptions

Layout_Error: Identity, configuration, or metadata is corrupt
Busy_Error: Allocator metadata is active or abandoned
Poison_Error: Arena lifecycle is poisoned

Attach_Allocation

procedure Attach_Allocation
  (Region : in out Region_View; Item : Algorithm.View; Value : Allocation_Algorithms.Allocation_Handle)

Attach Region to the exact bytes of a live allocation. The region must be detached before release or backing-mapping destruction.

Parameters

Region: Process-local allocation-region view attached on success
Item: Attached arena view
Value: Live allocation handle

Bind_Allocation

function Bind_Allocation
  (Item      : Algorithm.View;
   Value     : Allocation_Algorithms.Allocation_Handle;
   Offset    : Byte_Count;
   Extent    : Byte_Count;
   Alignment : Byte_Count;
   Signature : Interfaces.Unsigned_64;
   Version   : Interfaces.Unsigned_32;
   Writable  : Boolean) return Immutable_Storage_View

Bind one checked allocation slice for an immutable element adapter.

Parameters

Item: Attached arena view
Value: Live allocation handle
Offset: Byte offset within the allocation
Extent: Exact immutable representation bytes
Alignment: Required power-of-two native alignment
Signature: Stable immutable representation signature
Version: Immutable representation layout version
Writable: Whether an unpublished builder may bind the slice

Return value

Opaque checked immutable-storage binding @exclude

Block_Capacity

function Block_Capacity
  (Item : Algorithm.View; Value : Allocation_Algorithms.Allocation_Handle) return Byte_Count

Return the rounded capacity of a live allocation.

Parameters

Item: Attached arena view
Value: Live allocation handle

Return value

Usable bytes in the selected block

Raised exceptions

Handle_Error: Value is invalid or stale

Capabilities

Capabilities : constant Allocation_Algorithms.Allocation_Capabilities := Algorithm.Capabilities;

Compile-time behavioral characteristics of the selected algorithm.

Configuration

subtype Configuration is Algorithm.Configuration;

Algorithm-specific immutable creation parameters.

Copy

procedure Copy
  (Item          : Algorithm.View;
   Source        : Allocation_Algorithms.Allocation_Handle;
   Source_Offset : Byte_Count;
   Target        : Allocation_Algorithms.Allocation_Handle;
   Target_Offset : Byte_Count;
   Length        : Byte_Count)

Copy between two live allocation slices.

Parameters

Item: Attached arena view
Source: Source allocation handle
Source_Offset: Byte offset in Source
Target: Target allocation handle
Target_Offset: Byte offset in Target
Length: Bytes to copy; zero performs validation only

Create_Or_Attach

procedure Create_Or_Attach
  (Item          : out Algorithm.View;
   Region        : Region_View;
   Location      : Region_Offset;
   Configuration : Algorithm.Configuration;
   Instance_ID   : Interfaces.Unsigned_64;
   Result        : out Open_Result)

Atomically initialize allocation-certified virgin bytes or attach to a ready compatible arena. Algorithm identity, every configuration field, and Instance_ID must match an existing arena. This is not recovery.

Parameters

Item: Attached view or detached during another initialization
Region: Independently attached backing region
Location: Stored arena offset
Configuration: Expected algorithm-specific geometry
Instance_ID: Expected nonzero arena identity
Result: Creation, attachment, or in-progress outcome

Current_Metadata

function Current_Metadata (Item : Algorithm.View) return Allocation_Algorithms.Metadata

Return the immutable common arena configuration.

Parameters

Item: Attached arena view

Return value

Validated capacity, allocation unit, identity, and incarnation

Destroy

procedure Destroy (Item : in out Algorithm.View)

Destroy an empty quiescent arena and detach Item.

Parameters

Item: Exclusively synchronized arena view

Raised exceptions

Layout_Error: Live allocations remain

Detach

procedure Detach (Item : in out Algorithm.View)

Detach Item without releasing allocations or modifying backing bytes.

Parameters

Item: Local view to detach

Exhausted

Exhausted : constant Allocation_Result := Allocation_Algorithms.Exhausted;

No free block can satisfy the request.

Identity

Identity : constant Layout_Identity := Algorithm.Identity;

Complete persisted allocator identity.

Initialize

procedure Initialize
  (Item          : out Algorithm.View;
   Region        : Region_View;
   Location      : Region_Offset;
   Configuration : Algorithm.Configuration;
   Instance_ID   : Interfaces.Unsigned_64)

Destructively initialize an empty arena and attach Item. The caller must exclusively own the complete extent. Reinitialization invalidates every allocation handle and dependent structure.

Parameters

Item: View attached on success
Region: Attached caller-owned backing region
Location: Nonzero suitably aligned stored location
Configuration: Algorithm-specific immutable geometry
Instance_ID: Nonzero caller-selected arena identity

Is_Attached

function Is_Attached (Item : Algorithm.View) return Boolean

Report whether Item retains process-local mapping information.

Parameters

Item: View to inspect

Return value

True while the local arena view is attached

Is_Poisoned

function Is_Poisoned (Item : Algorithm.View) return Boolean

Report whether an attached arena was explicitly poisoned.

Parameters

Item: Attached arena view

Return value

True only for the persisted Poisoned lifecycle state

Metadata

subtype Metadata is Allocation_Algorithms.Metadata;

Immutable stored arena configuration.

Minimum_Block_Limit

Minimum_Block_Limit : constant Positive := Algorithm.Minimum_Block_Limit;

Minimum allocation unit accepted by the selected algorithm.

Null_Allocation

Null_Allocation : constant Allocation_Handle := Allocation_Algorithms.Null_Allocation;

Null allocation relationship.

Poison

procedure Poison (Region : Region_View; Location : Region_Offset)

Poison an arena only after the selected algorithm's documented external owner-death and quiescence conditions are established.

Parameters

Region: Attached backing region
Location: Stored arena offset

Read

procedure Read
  (Item   : Algorithm.View;
   Value  : Allocation_Algorithms.Allocation_Handle;
   Offset : Byte_Count;
   Data   : out Ada.Streams.Stream_Element_Array)

Copy a checked allocation slice into Data.

Parameters

Item: Attached arena view
Value: Live allocation handle
Offset: Byte offset within the allocation
Data: Destination byte array

Release

procedure Release (Item : in out Algorithm.View; Value : Allocation_Algorithms.Allocation_Handle)

Release a live allocation. The caller must exclude every payload access through Value.

Parameters

Item: Any concurrently attached arena view
Value: Live handle issued by this arena incarnation

Raised exceptions

Busy_Error: Another caller owns allocator metadata
Handle_Error: Value is null, stale, reclaimed, or foreign

Release

procedure Release
  (Item : in out Algorithm.View; Value : Allocation_Algorithms.Allocation_Handle; Timeout : Wait_Timeout)

Release after waiting for allocator-metadata contention.

Parameters

Item: Any concurrently attached arena view
Value: Live handle issued by this arena incarnation
Timeout: Maximum wait; zero permits one immediate attempt

Raised exceptions

Timeout_Error: Metadata contention persists through deadline

Required_Storage

function Required_Storage (Configuration : Algorithm.Configuration) return Byte_Count

Compute the complete allocator extent for Configuration.

Parameters

Configuration: Algorithm-specific immutable geometry

Return value

Complete allocator metadata, padding, and payload bytes

Raised exceptions

Constraint_Error: Configuration is invalid or unrepresentable

Try_Allocate

procedure Try_Allocate
  (Item           : in out Algorithm.View;
   Requested_Size : Positive;
   Value          : out Allocation_Algorithms.Allocation_Handle;
   Result         : out Allocation_Algorithms.Allocation_Result)

Attempt one variable-size allocation without waiting.

Parameters

Item: Any concurrently attached arena view
Requested_Size: Positive payload bytes requested
Value: New handle or Null_Allocation
Result: Allocated, exhausted, or contended outcome

Try_Allocate

procedure Try_Allocate
  (Item           : in out Algorithm.View;
   Requested_Size : Positive;
   Timeout        : Wait_Timeout;
   Value          : out Allocation_Algorithms.Allocation_Handle;
   Result         : out Allocation_Algorithms.Allocation_Result)

Allocate after waiting only for allocator-metadata contention. Genuine exhaustion still returns Exhausted after one complete attempt.

Parameters

Item: Any concurrently attached arena view
Requested_Size: Positive payload bytes requested
Timeout: Maximum wait; zero permits one immediate attempt
Value: New handle or Null_Allocation
Result: Allocated or exhausted outcome

Raised exceptions

Timeout_Error: Metadata contention persists through deadline

View

subtype View is Algorithm.View;

Process-local attached arena view. It owns neither the backing region nor an allocation and must be detached before its mapping disappears.

Write

procedure Write
  (Item   : Algorithm.View;
   Value  : Allocation_Algorithms.Allocation_Handle;
   Offset : Byte_Count;
   Data   : Ada.Streams.Stream_Element_Array)

Copy Data into a checked allocation slice.

Parameters

Item: Attached arena view
Value: Live allocation handle
Offset: Byte offset within the allocation
Data: Source byte array