InstrumentedDispatcher

A CoroutineDispatcher that wraps delegate and records how many blocks were dispatched, how many ran concurrently at peak, and the longest queue delay (dispatch to block start). Useful to detect saturated dispatchers while diagnosing slow or starved coroutines.

It is a convenience over TracingDispatcher plus StatsSink: it owns one of each and reports DispatcherStats, a three-number view of DispatcherMetrics. For richer data (latency histograms and percentiles, pending and failure counts, signals, thread information) build a TracingDispatcher with a StatsSink directly.

Diagnostic tool, opt-in, not meant for production. Wrapping a dispatcher such as Dispatchers.IO hides its limitedParallelism and elasticity hints from the coroutines machinery, so behavior can differ slightly from the unwrapped dispatcher. It also costs a few tens of nanoseconds and some allocation per dispatch (rough, unbenchmarked measurement on JVM).

It also forwards Delay: when delegate has its own delay implementation (for example a TestDispatcher, whose virtual time delay and withTimeout must honor), timers are scheduled on it. Otherwise the standard default delay is used. Either way the coroutine resumes through this dispatcher, so the resume is counted exactly once.

Counters are thread-safe and lock-free; read them with snapshot and zero them with reset.

Example:

val io = InstrumentedDispatcher(Dispatchers.ioCompat, "io")
withContext(io) { api.fetch() }
println(io.snapshot()) // DispatcherStats(label=io, totalDispatched=1, ...)

Rules: DISPATCH_005 (dispatchers are injected, so they can be wrapped). See docs/BEST_PRACTICES_COROUTINES.md section 3.5.

Requires opting in to ExperimentalStructuredCoroutines.

Parameters

See also