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.
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;
Dispatches : Counter;
Poll_Batches : Counter;
Poll_Events : Counter;
Wakeups : Counter;
Migrations_In : Counter;
Migrations_Out : 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
- 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
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
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
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