kumulant/com.eignex.kumulant.core/DiscreteStat

DiscreteStat

interface DiscreteStat<R : Result> : Stat<R> (source)

Accumulator over a stream of discrete Long values. The Long carries two interpretations across the family:

Opaque keys: cardinality estimators (HyperLogLogStat), heavy-hitter sketches (SpaceSavingStat), Bloom filters (BloomFilterStat). The numeric value of the Long is irrelevant; only equality matters. Hash domain-specific keys through com.eignex.kumulant.math.hash64 first so the input carries uniform 64-bit entropy.
Integer-valued measurements: Poisson counts, time deltas, integer histograms. Here the value is meaningful and arithmetic is applied to it.

Each concrete stat documents which interpretation it uses.

Inheritors

Properties

concurrency

abstract 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:

Functions

create

abstract override fun create(concurrency: Concurrency? = null): DiscreteStat<R>

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

abstract fun merge(values: R)

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

abstract fun read(timestampNanos: Long = currentTimeNanos()): R

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

abstract 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 fun update(value: Long, weight: Double = 1.0)

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

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

Record an observation at timestampNanos with the given weight. Time matters for rate-shaped discrete stats; for cardinality / sketch stats the stamp is dropped.

create

abstract override fun create(concurrency: Concurrency? = null): DiscreteStat<R>(source)

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.

The returned stat is independent: its state starts at the configured baseline, not at the source's current state. Each modality subtype narrows the return type so chaining doesn't lose the modality.

update

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

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

abstract fun update(value: Long, timestampNanos: Long, weight: Double = 1.0)(source)

Record an observation at timestampNanos with the given weight. Time matters for rate-shaped discrete stats; for cardinality / sketch stats the stamp is dropped.