Module queue_tracker 

Centralized bounded-queue usage tracker.

secure-exec streams guest output through a chain of bounded queues: the V8 -> host event channel, the sidecar stdout/stdin frame queues, and so on. Each queue applies backpressure when full (it parks the producer until the consumer drains) rather than crashing, but backpressure is invisible: a slow host consumer silently stalls a session with nothing in the logs.

This module gives that whole chain a single, inspectable home:

• Every bounded queue registers a QueueGauge (with a stable name and its capacity) in a process-global QueueRegistry.
• Producers report depth as they enqueue (either by an exact count for manually-tracked queues via TrackedSyncSender, or by sampling the live depth of a Tokio channel via QueueGauge::observe_depth).
• When a queue crosses WARN_FILL_PERCENT of capacity the gauge emits a single warn!, so “the consumer is falling behind” shows up before the queue saturates and backpressure stalls the session. It re-arms once the queue drains back below REARM_FILL_PERCENT.
• queue_snapshot returns the live depth / high-water / capacity of every registered queue for debugging or a status endpoint.

Structs

LimitWarning

A near-capacity event for one limit, delivered to the global warning sink at the same edge as the tracing::warn!. This is the structured payload a host hook (e.g. agentOS onLimitWarning) is built from.

QueueGauge

Live usage gauge for a single bounded queue.

QueueRegistry

Process-global registry of every live QueueGauge.

QueueSnapshot

Immutable view of a tracked limit’s usage, returned by queue_snapshot.

TrackedReceiver

Receiver half of a tracked_sync_channel; records a dequeue for every item it yields so the gauge depth tracks the real backlog.

TrackedSyncSender

A std::sync::mpsc::SyncSender that feeds a QueueGauge as items flow through it, so a queue whose backing channel cannot report its own length still participates in the centralized tracker.

Enums

LimitCategory

What class of bounded resource a gauge tracks. Lets a snapshot / a host hook group and reason about limits beyond just queues.

TrackedLimit

Stable catalog of tracked limits that may emit near-capacity or exhaustion warnings. Keep website/src/content/docs/docs/features/resource-limits.mdx in sync when adding, removing, or renaming variants so host-visible warning names and the documented constants do not drift.

Constants

REARM_FILL_PERCENT

Fill fraction a near-full queue must drain back below before it will warn again. The gap to WARN_FILL_PERCENT provides hysteresis so a queue hovering at the threshold does not flap.

WARN_FILL_PERCENT

Fill fraction (percent of capacity) at or above which a queue is considered “near full” and emits a warning. Edge-triggered so a steadily-full queue logs once, not on every enqueue.

Functions

log_queue_snapshot

Emit a debug! line for every registered queue. Useful for an on-demand dump of the queue chain when diagnosing a stall.

queue_snapshot

Snapshot every registered queue from the global registry.

register_limit

Register a non-queue bounded limit (a saturating resource or memory envelope) with the global registry, so it shares the same approach-warning + snapshot machinery as queues. Observe usage with QueueGauge::observe_depth.

register_queue

Register a bounded queue (the LimitCategory::Queue case) with the global registry. Convenience over QueueRegistry::global + QueueRegistry::register.

set_limit_warning_handler

Install a process-global sink that is invoked on the same edge-triggered, hysteresis-gated boundary as the tracing::warn! whenever a tracked limit crosses WARN_FILL_PERCENT. The sidecar uses this to forward limit warnings to the host as structured events (the onLimitWarning hook). The handler must be cheap and non-blocking; it runs on the producer’s thread.

tracked_sync_channel

Create a bounded std::sync::mpsc sync-channel whose depth is tracked by a registered QueueGauge. Drop-in for std::sync::mpsc::sync_channel plus centralized usage tracking + near-capacity warnings.

warn_limit_exhausted

Emit a structured/logged warning for a limit that has already been exhausted. Use this for runtime caps such as CPU or heap exhaustion where there is no continuously sampled queue depth to observe before the terminal edge.