Data.Metrics.Reservoir.Uniform

A histogram with a uniform reservoir produces quantiles which are valid for the entirely of the histogram’s lifetime. It will return a median value, for example, which is the median of all the values the histogram has ever been updated with. It does this by using an algorithm called Vitter’s R), which randomly selects values for the reservoir with linearly-decreasing probability.

Use a uniform histogram when you’re interested in long-term measurements. Don’t use one where you’d want to know if the distribution of the underlying data stream has changed recently.

Documentation

data UniformReservoir

A reservoir in which all samples are equally likely to be evicted when the reservoir is at full capacity.

This is conceptually simpler than the ExponentiallyDecayingReservoir, but at the expense of providing a less accurate sample.

reservoir

Arguments

:: Seed

-> Int

maximum reservoir size

-> Reservoir

Make a safe uniform reservoir. This variant provides safe access at the expense of updates costing O(n)

unsafeReservoir :: Seed -> Int -> Reservoir

Using this variant requires that you ensure that there is no sharing of the reservoir itself.

In other words, there must only be a single point of access (an IORef, etc. that accepts some sort of modification function).

In return, updating the reservoir becomes an O(1) operation and clearing the reservoir avoids extra allocations.

clear :: NominalDiffTime -> UniformReservoir -> UniformReservoir

Reset the reservoir to empty.

unsafeClear :: NominalDiffTime -> UniformReservoir -> UniformReservoir

Reset the reservoir to empty by performing an in-place modification of the reservoir.

size :: UniformReservoir -> Int

Get the current size of the reservoir

snapshot :: UniformReservoir -> Snapshot

Take a snapshot of the reservoir by doing an in-place unfreeze.

This should be safe as long as unsafe operations are performed appropriately.

update :: Double -> NominalDiffTime -> UniformReservoir -> UniformReservoir

Perform an update of the reservoir by copying the internal vector. O(n)

unsafeUpdate :: Double -> NominalDiffTime -> UniformReservoir -> UniformReservoir

Perform an in-place update of the reservoir. O(1)