kumulant/com.eignex.kumulant.stat.rate/DecayingRateStat

DecayingRateStat

class DecayingRateStat(val halfLife: Duration, val concurrency: Concurrency = Concurrency.None) : SeriesStat<DecayingRateResult> (source)

Time-decayed rate with the given halfLife.

Projects DecayingSumStat onto events-per-second via alpha = ln 2 / halfLife, so the rate reflects only the recent window of activity.

Use cases: recent throughput / events-per-second (request rate over the last 30 s, recent error rate). Reach for this over RateStat when older activity should fade.

Memory: O(1); one DecayingSumStat plus a scalar projection.

Update: O(1) per observation (one DecayingSumStat.update call).

Concurrency: Inherits DecayingSumStat's concurrency model; lock-free and exact under every Concurrency level.

Constructors

DecayingRateStat

constructor(halfLife: Duration, concurrency: Concurrency = Concurrency.None)

Properties

concurrency

open override val concurrency: Concurrency

The thread-safety contract this stat was constructed with. Each stat picks the cell-encoding and lock strategy that honours this contract for its mathematical structure:

halfLife

val halfLife: Duration

Functions

create

open override fun create(concurrency: Concurrency? = null): SeriesStat<DecayingRateResult>

Spawn a fresh accumulator with the same configuration. Optionally override the Concurrency; useful for materialising a wire spec at a different concurrency level than the source.

merge

open override fun merge(values: DecayingRateResult)

Fold another accumulator's snapshot into this one. The unit of merge is the immutable Result; not a live Stat; which is what lets the merge cross a process boundary. Many workers track slices of the same stream, call read periodically, ship snapshots to a coordinator, and the coordinator merges them in.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): DecayingRateResult

Materialise the current state as an immutable Result. Reads never mutate, so the caller can read as often as it likes without affecting the stream.

reset

open override fun reset()

Reset the stat to its prior-seeded baseline. Equivalent to constructing a fresh stat with the same configuration, but in place; keeps the same Concurrency and any per-stat tunables.

update

open override fun update(value: Double, weight: Double = 1.0)

Record an observation with the given weight, stamped at the current time.

open override fun update(value: Double, timestampNanos: Long, weight: Double = 1.0)

Record an observation at timestampNanos with the given weight. Stats that consume time (rates, decay, windowing) use this as the ordering signal; pass a monotonic stamp when feeding from a replay log.