Description
Exposes inert runtime snapshots for diagnostics and monitoring.
Example:
Available := Flyology.Observability.Snapshot (0, Current);
Counter
subtype Counter is Interfaces.Unsigned_64;
Unsigned process-lifetime counter; values wrap modulo Counter'Modulus.
Current_Task_Instance
function Current_Task_Instance return Task_Instance_Id
Return the calling lightweight task's process-lifetime diagnostic identity without acquiring a runtime lock. A native task, including the environment task, receives No_Task_Instance.
Return value
Calling lightweight task identity or No_Task_Instance
Event_Thread_State
type Event_Thread_State is (Starting, Running, Failed);
Lifecycle of one event-loop scheduler thread.
Enumeration literals
- Starting
The thread is entering scheduler startup
- Running
The scheduler loop is active
- Failed
Startup or scheduler execution failed
Fatal_Context
type Fatal_Context is
(No_Fatal, Scheduler_Invariant, Mutex_Failure, Poller_Failure, Context_Switch_Failure, Fork_Child_Use);
Classification recorded immediately before a fatal runtime abort.
Enumeration literals
- No_Fatal
No fatal path has been recorded
- Scheduler_Invariant
A scheduler state invariant failed
- Mutex_Failure
A runtime mutex operation failed
- Poller_Failure
The host event poller failed
- Context_Switch_Failure
A fiber context transition failed
- Fork_Child_Use
Unsupported runtime use occurred after fork
Group_Id
subtype Group_Id is Flyology.Execution_Groups.Group_Id;
Execution-group identifier used by observability calls.
Group_Snapshot
type Group_Snapshot is record
Group : Group_Id;
Thread_State : Event_Thread_State;
Dedicated : Boolean;
Reserved : Boolean;
Members : Counter;
Pinned_Members : Counter;
Ready : Counter;
Waiting : Counter;
Running : Counter;
Migrating : Counter;
Finished : Counter;
Timer_Waits : Counter;
Descriptor_Waits : Counter;
Interrupt_Waits : Counter;
File_Waits : Counter;
Pending_File_Submissions : Counter;
Dormancy_Candidates : Counter;
Dormancy_Candidate_Bytes : Counter;
Cold_Stacks : Counter;
Cold_Stack_Bytes : Counter;
Cold_Advice_Attempts : Counter;
Cold_Advice_Accepted : Counter;
Cold_Advice_Failures : Counter;
Pageout_Advice_Attempts : Counter;
Pageout_Advice_Accepted : Counter;
Pageout_Advice_Failures : Counter;
Dispatches : Counter;
Poll_Batches : Counter;
Poll_Events : Counter;
Wakeups : Counter;
Migrations_In : Counter;
Migrations_Out : Counter;
Uptime_Nanoseconds : Counter;
Idle_Nanoseconds : Counter;
Idle_Waits : Counter;
end record;
Consistent queue state plus cumulative counters for one permanent group.
Record fields
- Group
Execution group represented by the snapshot
- Thread_State
Current scheduler-thread lifecycle state
- Dedicated
Whether Group is in the dedicated range
- Reserved
Whether a lightweight task currently reserves Group
- Members
Current registered fibers in Group
- Pinned_Members
Current fibers with at least one thread pin
- Ready
Current runnable fibers
- Waiting
Current suspended fibers
- Running
Current executing fibers, normally zero or one
- Migrating
Current fibers transferring to another group
- Finished
Current fibers awaiting reap
- Timer_Waits
Current timer-suspended fibers
- Descriptor_Waits
Current single-descriptor waits
- Interrupt_Waits
Current waits with cancellation descriptors
- File_Waits
Current submitted file operations awaiting completion
- Pending_File_Submissions
Current file requests queued for submit
- Dormancy_Candidates
Timer-only waits safe for stack reclamation
- Dormancy_Candidate_Bytes
Usable stack bytes of those candidates
- Cold_Stacks
Current stacks with accepted cold or page-out advice
- Cold_Stack_Bytes
Usable bytes in those currently advised stacks
- Cold_Advice_Attempts
Cumulative host cold-advice calls
- Cold_Advice_Accepted
Cumulative accepted cold-advice calls
- Cold_Advice_Failures
Cumulative failed cold-advice calls
- Pageout_Advice_Attempts
Cumulative host page-out-advice calls
- Pageout_Advice_Accepted
Cumulative accepted page-out calls
- Pageout_Advice_Failures
Cumulative failed page-out calls
- Dispatches
Cumulative fiber dispatches
- Poll_Batches
Cumulative event-poller batches
- Poll_Events
Cumulative host events delivered
- Wakeups
Cumulative task wake requests
- Migrations_In
Cumulative migrations entering Group
- Migrations_Out
Cumulative migrations leaving Group
- Uptime_Nanoseconds
Elapsed nanoseconds since Group's scheduler thread entered its dispatch loop, or zero before it started
- Idle_Nanoseconds
Nanoseconds of Uptime_Nanoseconds in which Group had no runnable task and was blocked in its event poller. This never exceeds Uptime_Nanoseconds, so the difference is the time the loop spent running task code and its own scheduler work. Tasks suspended on readiness or a deadline make their group idle by this measure; use Waiting and Descriptor_Waits to distinguish an unloaded group from a blocked one
- Idle_Waits
Cumulative blocking event-poller waits
Has_Flag
function Has_Flag (Item : Task_Snapshot; Flag : Task_Flags) return Boolean
Test one flag in a copied task snapshot.
Parameters
- Item
Snapshot to inspect
- Flag
Flag value to test
Return value
True when Flag is set in Item
Last_Fatal
function Last_Fatal return Fatal_Context
Read the lock-free fatal classification retained before runtime abort.
Return value
No_Fatal during normal execution, otherwise the last fatal class
Made_Progress
function Made_Progress (Earlier : Group_Snapshot; Later : Group_Snapshot) return Boolean
Test whether dispatch or polling counters changed between snapshots. This avoids adding a clock read to each scheduler dispatch.
Parameters
- Earlier
Older snapshot of a group
- Later
Newer snapshot of the same group
Return value
True when dispatches, poll batches, or poll events advanced
No_Task_Instance
No_Task_Instance : constant Task_Instance_Id := 0;
Sentinel that is never assigned to a lightweight task instance.
Snapshot
function Snapshot (Group : Group_Id; Result : out Group_Snapshot) return Boolean
Capture Group while holding its scheduler lock. The query is thread-safe and inert: it does not start a group or allocate scheduler resources.
Parameters
- Group
Execution group to observe
- Result
Snapshot written when the group exists
Return value
True when Group has been created; False otherwise
Raised exceptions
- Program_Error
Runtime and library observability ABIs differ
Snapshot_Tasks
function Snapshot_Tasks
(Group : Group_Id; Items : in out Task_Snapshot_Array; Count : out Natural; Total : out Counter)
return Boolean
Copy a bounded prefix of Group's lightweight task membership while holding the topology and selected group scheduler locks. No allocation or callback occurs while locked. List order is unspecified. Entries are coherent with one another, but a later call may observe migration, creation, or reap. Only Items (Items'First .. Items'First + Count - 1) is overwritten; the remainder retains its incoming value. Total reports the complete group membership, so Count < Total indicates truncation.
Parameters
- Group
Execution group to observe
- Items
Caller-owned nonempty output buffer
- Count
Number of entries copied into Items
- Total
Complete group membership at the snapshot instant
Return value
True when Group exists; False without starting event machinery
Raised exceptions
- Constraint_Error
Items is empty
- Program_Error
Runtime and library task snapshot ABIs differ
Stack_Pool
function Stack_Pool return Stack_Pool_Snapshot
Capture process-wide stack allocation without creating an event loop. Adjacent stacks share an inaccessible guard page and remain guarded on both sides. Empty arenas are unmapped. MADV_DONTNEED is best effort. The query is thread-safe.
Return value
Current stack-pool state and cumulative counters
Raised exceptions
- Program_Error
Runtime and library stack-pool ABIs differ
Stack_Pool_Snapshot
type Stack_Pool_Snapshot is record
Active_Arenas : Counter;
Live_Stacks : Counter;
Live_Usable_Bytes : Counter;
Reserved_Bytes : Counter;
Arena_Mappings : Counter;
Arena_Unmappings : Counter;
Shared_Stacks : Counter;
Discarded_Stacks : Counter;
end record;
Process-wide lightweight stack allocator state and cumulative counters.
Record fields
- Active_Arenas
Current mapped stack arenas
- Live_Stacks
Current allocated fiber stacks
- Live_Usable_Bytes
Current requested usable stack bytes
- Reserved_Bytes
Current virtual bytes reserved for arenas
- Arena_Mappings
Cumulative arena mappings
- Arena_Unmappings
Cumulative arena unmaps
- Shared_Stacks
Cumulative stacks placed in an existing arena
- Discarded_Stacks
Cumulative accepted MADV_DONTNEED releases
Task_Descriptor_Wait_Flag
Task_Descriptor_Wait_Flag : constant Task_Flags := 2#000100#;
The task is waiting for descriptor readiness.
Task_Destroy_Requested_Flag
Task_Destroy_Requested_Flag : constant Task_Flags := 2#100000#;
Reap was requested while the fiber was still running or migrating.
Task_File_Pending_Flag
Task_File_Pending_Flag : constant Task_Flags := 2#010000#;
The task's file request is queued for kernel submission.
Task_File_Wait_Flag
Task_File_Wait_Flag : constant Task_Flags := 2#001000#;
The task owns an in-flight or queued file request.
Task_Flags
type Task_Flags is mod 2**32 with Size => 32, Convention => C;
Bit set copied with a lightweight task snapshot.
Task_Instance_Id
type Task_Instance_Id is new Interfaces.Unsigned_64;
Process-lifetime identity of one lightweight task instance. The value is diagnostic only: it is not an Ada Task_Id or a task-control handle.
Task_Pinned_Flag
Task_Pinned_Flag : constant Task_Flags := 2#000001#;
The task holds at least one thread pin.
Task_Snapshot
type Task_Snapshot is record
Instance : Task_Instance_Id := No_Task_Instance;
State : Task_State := Task_Waiting;
Base_Priority : Interfaces.Integer_32 := 0;
Flags : Task_Flags := 0;
Stack_Usable_Bytes : Counter := 0;
end record;
Copied diagnostic state for one lightweight task. Instance remains stable across migration and is never reused during the process lifetime.
Record fields
- Instance
Process-lifetime lightweight task instance identity
- State
Scheduler state at the group snapshot instant
- Base_Priority
Current GNARL base priority
- Flags
Pinned, wait, pending-file, and deferred-reap flags
- Stack_Usable_Bytes
Usable guarded-stack bytes, or zero after the finished stack is released
Task_Snapshot_Array
type Task_Snapshot_Array is array (Positive range <>) of Task_Snapshot with Convention => C;
Caller-owned output buffer for bounded lightweight task enumeration.
Task_State
type Task_State is (Task_Ready, Task_Waiting, Task_Running, Task_Migrating, Task_Finished)
with Convention => C;
Scheduler state copied for one lightweight task.
Enumeration literals
- Task_Ready
The task is runnable
- Task_Waiting
The task is suspended
- Task_Running
The task is executing on its event loop
- Task_Migrating
The task is transferring between groups
- Task_Finished
The task body finished and awaits reap
Task_Timer_Wait_Flag
Task_Timer_Wait_Flag : constant Task_Flags := 2#000010#;
The task is registered in the group deadline heap.