PoolSampler

Periodically turns the cumulative state of a StatsSink into TraceEvent.PoolSamples so a pool can be watched over time. One sample is emitted per dispatcher label that stats knows.

The sampling loop never ends by itself. In runTest, launch it in backgroundScope (a plain TestScope.launch would keep the test from finishing), and do not run it on a dispatcher that this same sampler measures: its own delay resumes would show up in the stats.

Nothing runs by itself: no coroutine is created until launchIn is called, and then it runs in the caller's scope and is cancelled with it. Call sampleOnce to sample manually. Samples are emitted at TraceLevel.Pool and skipped entirely when sink is not enabled for it; feed a sink such as RingBufferSink(256, TraceLevel.Pool) and stats must be fed by a traced provider.

Timestamps are nanoseconds on a monotonic base: the time elapsed since this sampler was created. Only differences between samples of the same sampler are meaningful. A faulty sink never propagates an Exception to the caller.

Example:

val stats = StatsSink()
val ring = RingBufferSink(512, TraceLevel.Pool)
val traced = DefaultDispatcherProvider.traced(stats)
val sampler = PoolSampler(stats, ring, traced::parallelism)
val job = sampler.launchIn(scope, 500.milliseconds)
// later
ring.snapshot().filterIsInstance<TraceEvent.PoolSample>().signals().forEach(::println)

Thread-safety: sampleOnce can be called from any thread; the sampled counters come from the lock-free StatsSink.

Requires opting in to ExperimentalStructuredCoroutines.

Parameters

See also