com.eignex.kumulant/stat/summary/ArgMaxStat

ArgMaxStat

class ArgMaxStat(val concurrency: Concurrency = Concurrency.None) : SeriesStat<ArgMaxResult> (source)

Tracks the maximum value seen across a stream together with the timestamp at which it occurred. On ties the first occurrence wins.

Use cases: best objective and when it was found, peak load and when it happened, locating the peak of a series in time.

Memory: O(1); a double cell, a long cell, and a lock.

Update: O(1) per observation.

Concurrency: Internal CAS spin-lock (category 3). The (value, timestamp) pair cannot be made elementwise atomic with a single-cell CAS; the lock keeps the pair consistent under any Concurrency level.

Constructors

ArgMaxStat

constructor(concurrency: Concurrency = Concurrency.None)(source)

Properties

concurrency

open override val concurrency: Concurrency(source)

Thread-safety mode fixed at construction. See Concurrency for the shared contract and the implementation's KDoc for its cell and lock strategy.

Functions

create

open override fun create(concurrency: Concurrency? = null): ArgMaxStat(source)

Create an independent accumulator at the configured baseline. A null concurrency preserves this accumulator's mode; a non-null value overrides it. Modality subtypes narrow the return type to preserve the input shape.

merge

open override fun merge(values: ArgMaxResult, timestampNanos: Long = currentTimeNanos())(source)

Fold a compatible snapshot values into this accumulator at timestampNanos. Implementations document whether the combine is exact or approximate and which state the snapshot omits. The source accumulator is unaffected.

Time-dependent statistics, such as windows, place the snapshot at timestampNanos, which must share the clock the caller uses for updates and reads. Time-independent statistics ignore it.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): ArgMaxResult(source)

Return the current result evaluated at timestampNanos. Time-independent statistics ignore the timestamp. Reading does not add an observation.

Snapshot consistency depends on the implementation's synchronisation. Locks protect coupled state under Concurrency.Strict and Concurrency.HighWrite; independently updated cells and JVM striped adders can still yield a best-effort snapshot. Concurrency.Relaxed permits drift across coupled cells.

reset

open override fun reset()(source)

Restore the configured baseline, including any prior seed. Preserves the configuration and concurrency.

update

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

Record value with weight at the current monotonic time.

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

Record value with weight at timestampNanos.

validateMerge

open fun validateMerge(values: ArgMaxResult)

Validate values for merge without changing accumulator state. Containers validate every child before merging any of them. Successful validation checks compatibility; it does not make a concurrent merge transactional.

update

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

Record value with weight at timestampNanos.