commonware-storage 2026.10.0

Persist and retrieve data from an abstract store.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

//! Metric handles that an [`Index`](super::Index) updates as it changes.
//!
//! A full index counts on its registered metrics directly. The index inside a parallel
//! snapshot-build worker counts on [`Batched`] handles that publish to the full index's metrics in
//! batches. Both implement these traits, so one implementation of the index serves either.

use commonware_runtime::telemetry::metrics::{Batched, Counter, Gauge, GaugeValue, raw};

/// A gauge that an index raises and lowers as keys and values come and go.
pub trait GaugeHandle: Send + Sync {
    /// Increase the gauge by one.
    fn inc(&mut self);

    /// Decrease the gauge by one.
    fn dec(&mut self);

    /// Decrease the gauge by `value`.
    fn dec_by(&mut self, value: GaugeValue);

    /// The gauge's value as seen through this handle.
    fn get(&self) -> GaugeValue;
}

/// A counter that an index raises as it prunes values or spills partitions.
pub trait CounterHandle: Send + Sync {
    /// Increase the counter by one.
    fn inc(&mut self);

    /// Increase the counter by `value`.
    fn inc_by(&mut self, value: u64);

    /// The counter's value as seen through this handle.
    fn get(&self) -> u64;
}

impl GaugeHandle for Gauge {
    fn inc(&mut self) {
        self.metric().inc();
    }

    fn dec(&mut self) {
        self.metric().dec();
    }

    fn dec_by(&mut self, value: GaugeValue) {
        self.metric().dec_by(value);
    }

    fn get(&self) -> GaugeValue {
        self.metric().get()
    }
}

impl CounterHandle for Counter {
    fn inc(&mut self) {
        self.metric().inc();
    }

    fn inc_by(&mut self, value: u64) {
        self.metric().inc_by(value);
    }

    fn get(&self) -> u64 {
        self.metric().get()
    }
}

impl GaugeHandle for Batched<raw::Gauge> {
    fn inc(&mut self) {
        Self::inc(self);
    }

    fn dec(&mut self) {
        Self::dec(self);
    }

    fn dec_by(&mut self, value: GaugeValue) {
        Self::dec_by(self, value);
    }

    fn get(&self) -> GaugeValue {
        Self::get(self)
    }
}

impl CounterHandle for Batched<raw::Counter> {
    fn inc(&mut self) {
        Self::inc(self);
    }

    fn inc_by(&mut self, value: u64) {
        Self::inc_by(self, value);
    }

    fn get(&self) -> u64 {
        Self::get(self)
    }
}