Description
Saturating count of messages lost at a history boundary.
Batch
type Batch is limited private;
Exclusive consumer ownership of one detached trace buffer. Batch is limited so the handle cannot be copied; finalization releases it. The owner must exclude concurrent access to one Batch, particularly Release while an accessor is running. Do not request another batch from this package instance while retaining one; nested acquisition can wait on the caller's own reservation.
Batch_Statistics
type Batch_Statistics is record
Retained : Natural;
Overwritten : Loss_Count;
Dropped : Loss_Count;
Has_Traces : Boolean;
First_Sequence : Sequence_Number;
Last_Sequence : Sequence_Number;
end record;
Loss and sequence metadata transferred with a detached batch. Empty batches set Has_Traces to False and both sequence fields to zero.
Record fields
- Retained
Number of trace records in the batch
- Overwritten
Older records replaced while producing the batch
- Dropped
New messages declined while the batch was full
- Has_Traces
Whether First_Sequence and Last_Sequence are present
- First_Sequence
Producer-local order of the oldest retained record
- Last_Sequence
Producer-local order of the newest retained record
Capacity
Capacity : Positive := 1_024;
Clear
procedure Clear
Clear retained messages and both loss counters. Producer calls waiting in Block_Producer mode for producer one may then proceed.
Clear
procedure Clear (Producer : Producer_Id)
Clear retained messages and loss counters for an explicit producer. Producer calls waiting in Block_Producer mode for that producer may then proceed.
Parameters
- Producer
Producer shard whose retained state is discarded
Close
procedure Close
Permanently reject new traces. The operation is idempotent and wakes every producer blocked for history capacity; retained state remains available to Take or Clear.
Disable
procedure Disable
Reversibly ignore later producer operations and wake producers waiting in Block_Producer mode. Retained history remains available.
Enable
procedure Enable
Reversibly allow producer operations. Enable has no effect after Close.
Is_Acquired
function Is_Acquired (Result : Batch) return Boolean
Report whether Result owns a consumer reservation. This remains true if Take is interrupted after reserving its producer but before detachment, allowing a surviving owner to call Release safely.
Parameters
- Result
Consumer batch to inspect
Return value
True while Result must be released before another acquisition
Is_Acquired
function Is_Acquired (Result : Merged_Batch) return Boolean
Report whether Result owns a consumer reservation. This remains true if Take_Merged is interrupted after reserving all producers but before every buffer is detached, allowing a surviving owner to call Release safely.
Parameters
- Result
Merged consumer batch to inspect
Return value
True while Result must be released before another acquisition
Is_Closed
function Is_Closed return Boolean
Report whether Close has permanently closed this tracer instance.
Return value
True after Close has begun rejecting producer operations
Is_Enabled
function Is_Enabled return Boolean
Report whether producer operations are currently enabled. Callers may use this cheap atomic query to avoid constructing expensive messages. Concurrent state changes may take effect immediately before or after the query.
Return value
True when the tracer currently accepts producer operations
Loss_Count
subtype Loss_Count is Interfaces.Unsigned_64;
Saturating count of messages lost at a history boundary.
Merged_Batch
type Merged_Batch is limited private;
Exclusive consumer ownership of one detached buffer from every producer shard. The handle is limited and finalization releases all its buffers. The owner must exclude concurrent access to one Merged_Batch. Do not call Take or Take_Merged while retaining another batch from this instance.
Merged_Batch_Statistics
type Merged_Batch_Statistics is record
Retained : Interfaces.Unsigned_64;
Overwritten : Loss_Count;
Dropped : Loss_Count;
end record;
Aggregate retention and loss metadata for a merged batch. Aggregate counters saturate if producer totals cannot be represented.
Record fields
- Retained
Number of trace records across all producer buffers
- Overwritten
Older records replaced across producer buffers
- Dropped
New messages declined across producer buffers
Message_Of
function Message_Of (Record_At : Trace_Record) return Message_Type
Return an independent copy of the payload in Record_At.
Parameters
- Record_At
Trace record to inspect
Return value
Submitted message value
Message_Type
type Message_Type is private;
Now
function Now return Timestamp
Return value
Overflow
Overflow : Overflow_Policy := Overwrite_Oldest;
Overwrite_Count
subtype Overwrite_Count is Loss_Count;
Count type returned by the overwrite-specific compatibility accessor.
Overwrites
function Overwrites (Result : Batch) return Overwrite_Count
Return oldest messages replaced by newer messages. The count saturates rather than wrapping and resets when a batch is detached or through Clear.
Parameters
- Result
Acquired batch to inspect
Return value
History overwrite count represented by Result
Raised exceptions
- Constraint_Error
Result does not own a buffer
Producer_Count
Producer_Count : Positive := 1;
Producer_Id
subtype Producer_Id is Positive range 1 .. Producer_Count;
Explicit producer shard. Assign distinct hot producers distinct ids to avoid shared-store contention. Sharing an id remains task safe, but its producers serialize with one another. Capacity is available separately to every id.
Producer_Of
function Producer_Of (Result : Batch) return Producer_Id
Return the producer shard from which Result was detached.
Parameters
- Result
Acquired batch to inspect
Return value
Producer supplied to Take
Raised exceptions
- Constraint_Error
Result does not own a buffer
Release
procedure Release (Result : in out Batch)
Return Result's detached buffer and consumer reservation for reuse. The operation is idempotent; finalization performs it automatically when necessary, including after an interrupted Take.
Parameters
- Result
Consumer batch to release
Release
procedure Release (Result : in out Merged_Batch)
Return every detached buffer and reservation owned by Result. The operation is idempotent; finalization also performs it automatically, including after an interrupted Take_Merged.
Parameters
- Result
Merged consumer batch to release
Select_Producer
function Select_Producer (Producer_Count : Positive) return Positive
Parameters
- Producer_Count
Return value
Sequence_Number
subtype Sequence_Number is Interfaces.Unsigned_64;
Modular order assigned to messages accepted by one producer's protected store. Retention order remains authoritative across the practically remote Unsigned_64 wrap boundary.
Sequence_Of
function Sequence_Of (Record_At : Trace_Record) return Sequence_Number
Return the protected-store admission order of Record_At.
Parameters
- Record_At
Trace record to inspect
Return value
Modular sequence number assigned when the record was retained
Statistics
function Statistics (Result : Batch) return Batch_Statistics
Return retention, loss, and admission-order metadata for Result.
Parameters
- Result
Acquired batch to inspect
Return value
Metadata captured with the detached buffer
Raised exceptions
- Constraint_Error
Result does not own a buffer
Statistics
function Statistics (Result : Merged_Batch) return Merged_Batch_Statistics
Return aggregate retention and loss metadata for Result.
Parameters
- Result
Acquired merged batch to inspect
Return value
Aggregate metadata from all detached producer buffers
Raised exceptions
- Constraint_Error
Result does not own all producer buffers
Take
procedure Take (Result : in out Batch)
Release any buffer currently held by Result, reserve Producer for this consumer, then atomically transfer its retained state while the producer uses its other preallocated buffer. Concurrent Take calls for one producer wait until the prior consumer releases its batch. Different producers may be taken independently. Producer calls waiting in Block_Producer mode may proceed once their producer's swap completes. Calling Take while retaining another batch from this package instance is unsupported because nested consumer reservations can deadlock.
Parameters
- Result
Exclusive handle replaced by producer one's detached batch
Take
procedure Take (Result : in out Batch; Producer : Producer_Id)
Transfer retained state from an explicit producer shard.
Parameters
- Result
Exclusive handle replaced by the detached trace batch
- Producer
Producer shard whose retained state is transferred
Take_Merged
procedure Take_Merged (Result : in out Merged_Batch)
Release buffers currently held by Result, then atomically reserve every producer before detaching any buffer. The subsequent producer swaps are individually atomic but are not a simultaneous cross-producer snapshot. Producers resume into their spare buffers after their individual swap. A merged take waits without retaining a partial set of producers. Calling it while retaining another batch from this package instance is unsupported because it would wait on the caller's own reservation.
Parameters
- Result
Exclusive handle replaced by all detached trace buffers
Timestamp_Of
function Timestamp_Of (Record_At : Trace_Record) return Timestamp
Return the producer timestamp of Record_At.
Parameters
- Record_At
Trace record to inspect
Return value
Monotonic nanosecond timestamp captured before history insertion
Trace
procedure Trace (Message : Message_Type)
Timestamp and retain Message without allocation or I/O when enabled. A disabled tracer silently ignores the operation. Overwrite_Oldest replaces the oldest record when full. Drop_Newest silently declines Message and increments Dropped. Block_Producer waits until Take or Clear releases capacity. After Close, the operation raises Closed_Error instead of waiting.
Parameters
- Message
Definite payload copied into the automatically selected producer
Raised exceptions
- Closed_Error
The tracer is closed
- Constraint_Error
Automatic selection returned an invalid id
Trace
procedure Trace (Message : Message_Type; Producer : Producer_Id)
Timestamp and retain Message in an explicit producer shard. Its policy and lifecycle behavior match Trace for producer one.
Parameters
- Message
Definite payload copied by the tracer
- Producer
Independent producer shard receiving Message
Raised exceptions
- Closed_Error
The tracer is closed
Trace_At
function Trace_At (Result : Batch; Index : Positive) return Trace_Record
Return one retained record in oldest-to-newest admission order. Calls from concurrent producers may be admitted in a different order from their captured timestamps.
Parameters
- Result
Acquired batch to inspect
- Index
One-based index not greater than Trace_Count
Return value
Timestamped copied message
Raised exceptions
- Constraint_Error
Result is unacquired or Index exceeds its trace count
Trace_Count
function Trace_Count (Result : Batch) return Natural
Return the number of valid retention-ordered trace records in Result.
Parameters
- Result
Acquired batch to inspect
Return value
Count in the range 0 .. Capacity
Raised exceptions
- Constraint_Error
Result does not own a buffer
Trace_Record
type Trace_Record is private;
One timestamped copy of a submitted message.
Try_Trace
procedure Try_Trace (Message : Message_Type; Accepted : out Boolean)
Attempt Trace without waiting for history capacity. Overwrite_Oldest always accepts after acquiring the protected store. Drop_Newest counts a full-history decline in the detached batch. Block_Producer declines immediately while history is full. Disabled and closed tracers also decline without calling Now.
Parameters
- Message
Definite payload offered to the automatically selected producer
- Accepted
True when Message was copied into history
Raised exceptions
- Constraint_Error
Automatic selection returned an invalid id
Try_Trace
procedure Try_Trace (Message : Message_Type; Accepted : out Boolean; Producer : Producer_Id)
Attempt Trace for an explicit producer shard without waiting for history capacity.
Parameters
- Message
Definite payload offered to the tracer
- Accepted
True when Message was copied into history
- Producer
Independent producer shard offered Message
Visit
procedure Visit
(Result : Batch;
Process :
not null access procedure
(Sequence : Sequence_Number;
Captured_At : Flyology_Debug.Timestamp;
Message : not null access constant Message_Type))
Visit retained messages in oldest-to-newest admission order without copying records or payloads. Message designates storage owned by Result and must not be retained after Process returns. Process must not release or replace Result while Visit is active. The callbacks run outside the protected store, so producers continue using the active buffer.
Parameters
- Result
Acquired batch to inspect
- Process
Consumer callback invoked once per retained message
Raised exceptions
- Constraint_Error
Result does not own a buffer
Visit_Merged
procedure Visit_Merged
(Result : Merged_Batch;
Process :
not null access procedure
(Producer : Producer_Id;
Sequence : Sequence_Number;
Captured_At : Flyology_Debug.Timestamp;
Message : not null access constant Message_Type))
Visit all retained messages without copying records or payloads. The merge preserves each producer's admission order and selects the earliest timestamp among the current producer heads, breaking equal timestamps by Producer_Id. It therefore does not reorder one producer's records even if concurrently captured timestamps differ from admission order. Message designates storage owned by Result and must not be retained after Process returns. Callbacks run outside all protected stores.
Parameters
- Result
Acquired merged batch to inspect
- Process
Consumer callback invoked once per retained message
Raised exceptions
- Constraint_Error
Result does not own all producer buffers