Struct metrics_util::Registry

pub struct Registry<K, H, G> where
    K: Eq + Hashable + Clone + 'static,
    H: 'static,  { /* fields omitted */ }

A high-performance metric registry.

Registry provides the ability to maintain a central listing of metrics mapped by a given key.

In many cases, K will be a composite key, where the fundamental Key type from metrics is present, and differentiation is provided by storing the metric type alongside.

Metrics themselves are represented opaquely behind H. In most cases, this would be a thread-safe handle to the underlying metrics storage that the owner of the registry can use to update the actual metric value(s) as needed. Handle, from this crate, is a solid default choice.

As well, handles have an associated generation counter which is incremented any time an entry is operated on. This generation is returned with the handle when querying the registry, and can be used in order to delete a handle from the registry, allowing callers to prune old/stale handles over time.

Registry is optimized for reads.

Implementations

impl<K, H, G> Registry<K, H, G> where
    K: Eq + Hashable + Clone + 'static,
    H: 'static, 

pub fn untracked() -> Registry<K, H, NotTracked<H>>

Creates a new Registry without generation semantics.

pub fn tracked() -> Registry<K, H, Tracked<H>>

Creates a new Registry with generation semantics.

In some use cases, there is a requirement to understand what “generation” a metric is, for the purposes of understanding if a given metric has changed between two points in time.

This registry wraps metrics with a generation counter, which is incremented every time a metric is operated on. When queried for a list of metrics, they’ll be provided with their current generation.

impl<K, H, G> Registry<K, H, G> where
    K: Eq + Hashable + Clone + 'static,
    H: 'static,
    G: Generational<H>, 

pub fn clear(&self)

Removes all metrics from the registry.

This operation is eventually consistent: metrics will be removed piecemeal, and this method does not ensure that callers will see the registry as entirely empty at any given point.

pub fn op<I, O, V>(&self, kind: MetricKind, key: &K, op: O, init: I) -> V where
    I: FnOnce() -> H,
    O: FnOnce(&H) -> V, 

Perform an operation on a given key.

The op function will be called for the handle under the given key.

If the key is not already mapped, the init function will be called, and the resulting handle will be stored in the registry.

pub fn delete(&self, kind: MetricKind, key: &K) -> bool

Deletes a handle from the registry.

Returns true if the handle existed and was removed, false otherwise.

pub fn delete_with_gen(
    &self,
    kind: MetricKind,
    key: &K,
    generation: Generation
) -> bool

Deletes a handle from the registry.

The generation of a given key is passed along when querying the registry via get_handles. If the generation given here does not match the current generation, then the handle will not be removed.

Returns true if the handle existed and was removed, false otherwise.

pub fn visit<F>(&self, collect: F) where
    F: FnMut(MetricKind, (&K, &G)), 

Visits every handle stored in this registry.

The given function will be passed the metric kind as well as the key and handle references, which are wrapped in Generational-implementing holders.

This operation does not lock the entire registry, but proceeds directly through the “subshards” that are kept internally. As a result, all subshards will be visited, but a metric that existed at the exact moment that visit was called may not actually be observed if it is deleted before that subshard is reached. Likewise, a metric that is added after the call to visit, but before visit finishes, may also not be observed.

pub fn get_handles(&self) -> HashMap<(MetricKind, K), (Generation, H)> where
    H: Clone, 

Gets a map of all present handles, mapped by key.

Handles must implement Clone. This map is a point-in-time snapshot of the registry.

Trait Implementations

impl<K: Debug, H: Debug, G: Debug> Debug for Registry<K, H, G> where
    K: Eq + Hashable + Clone + 'static,
    H: 'static, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K, H, G> Default for Registry<K, H, G> where
    K: Eq + Hashable + Clone + 'static,
    H: 'static,
    G: Generational<H>, 

fn default() -> Self

Returns the “default value” for a type.