resourcetrack 0.3.0

Basic tools for counting objects
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
99
100
101
102
103
104
105
106
107
108

# resourcetrack

Yet-another resource tracking tool.

Compared to the more general purpose and excellent `tokio::sync::broadcast`,
Splaycast is more application-specific and more amenable to huge numbers of
subscribers.

# About
A trim, low-dependency tool for counting things. This project does not
use `unsafe` code. It only depends on std.

Safety, clarity, flexibility, and performance are favored in descending order.
Counters are plain structs holding an Arc to an atomic usize. This means there
is a memory cost to the tracking. 0-overhead is not a goal here.

# Details
Resourcetrack supports static categories with your own names:
```rust
use resourcetrack::new_registry;

#[derive(Clone, Debug, PartialEq, Eq, Hash)]
enum MyCategories {
    Miscellaneous,
    Specific,
}

let registry = new_registry::<MyCategories>();
let specific_category_tracker = registry.category(MyCategories::Specific);
```

Resourcetrack does not explicitly synchronize categorized resource counters.
```rust
let _count_sentinel: Count = category_tracker.track(); // non-blocking, on both track and drop
```

Counters are a plain struct, and you can compose them onto your expensive business objects for
automatic count management. If you do this, you can consider using lazy_static for this Registry
to wrap up the counts inside of your constructor function. Ideally you'd cascade the lazy_static
into category Trackers too!
```rust
struct ExpensiveResource {
    payload: String,
    _phantom_count: resourcetrack::tracked::Count,
}
```

When you need to get the counts, for logging or metrics or whatever, just read them.
```rust
let registry = new_registry::<MyCategories>();
{
    let _counter_1 = registry.category(MyCategories::Specific).track();
    assert_eq!(vec![(MyCategories::Specific, 1)], registry.read_counts::<Vec<_>>(), "1 specific instance");
    let _counter_2 = registry.category(MyCategories::Specific).track();
    assert_eq!(vec![(MyCategories::Specific, 2)], registry.read_counts::<Vec<_>>(), "2 specific instances");
}

assert_eq!(vec![(MyCategories::Specific, 0)], registry.read_counts::<Vec<_>>(), "both dropped");
```

You can track sized resources, where their size changes. To stay sane, you should probably limit
yourself to either using track() or track_sized() for a given category. You can mix counts and sizes
within a registry though, no problem!
Complete example:
```rust
use resourcetrack::tracked;

// Set up your statically knowable categories
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
enum MyCategories {
    ResourceCount,
    ResourceWeight,
}

// Here is an example of a tracked business object. Both size and weight are tracked.
struct TrackedVector {
    internal: Vec<String>,
    _count_sentinel: tracked::Count,
    weight: tracked::Size,
}
impl TrackedVector {
    pub fn push(&mut self, next: String) {
        self.weight.add(next.len());
    }
}

// Static setup - this should be in some shared lazy static scope.
let registry = resourcetrack::new_registry::<MyCategories>();
let resource_counts = registry.category(MyCategories::ResourceCount);
let resource_weights = registry.category(MyCategories::ResourceWeight);

let mut v = TrackedVector { // This should be wrapped into TrackedVector::new() in your application
    internal: Default::default(),
    _count_sentinel: resource_counts.track(),
    weight: resource_weights.track_size(0),
};
v.push("hello".to_string());
//!
let mut counts = registry.read_counts::<Vec<_>>();
counts.sort();
assert_eq!(
    vec![
        (MyCategories::ResourceCount, 1),
        (MyCategories::ResourceWeight, 5),
    ],
    counts,
)
```