utally 1.0.1

Unique ids in static contexts
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
109
110
111

#![warn(missing_docs)]
//! # UTally
//!
//! This tool was created to allow easily creating unique ids for types in both static and dynamic
//! contexts. The ids are sequential, this is basically a tally counter.
//!
//! # Usage
//!
//! Call [next] to acquire a new unique id.
//!
//! ```rust
//! let unique_id = utally::next();
//! ```
//! ## Using it in a static context
//!
//! You can use [LazyTally] in order to assign ids to types or functions by using them in static
//! contexts:
//!
//! ```rust
//! # use utally::*;
//! pub fn function_with_unique_id() -> usize {
//!     static SOME_TALLY: LazyTally = LazyTally::new();
//!     SOME_TALLY.get()
//! }
//! ```
//!
//! A call to `function_with_unique_id` would always return the same unique id.
use std::sync::{
    Once,
    atomic::{AtomicUsize, Ordering},
};

/// Global tally counter
#[unsafe(export_name = "__utally_global_counter")]
pub static GLOBAL_COUNTER: Tally = Tally::new(1);

#[unsafe(export_name = "utally_next")]
/// Acquires a new unique id. This adds 1 to the tally.
pub extern "C" fn next() -> usize {
    GLOBAL_COUNTER.next()
}

#[unsafe(export_name = "utally_peek")]
/// Peeks to see which value would be returned in the next call for [next]. Because of concurrency,
/// this does not mean you can call [next] after [peek] and get the same result in both. This
/// function is designed to be used only in case you want to know where the tally is at, without
/// increasing the values.
pub extern "C" fn peek() -> usize {
    GLOBAL_COUNTER.peek()
}

/// A tally counter
#[repr(C)]
pub struct Tally {
    tally: AtomicUsize,
}

impl Tally {
    /// Creates a new tally counter initializing at `initial`.
    pub const fn new(initial: usize) -> Tally {
        Tally {
            tally: AtomicUsize::new(initial),
        }
    }

    /// Adds 1 to the tally and returns the previous value.
    pub fn next(&self) -> usize {
        self.tally.fetch_add(1, Ordering::Relaxed)
    }

    /// Returns the current value of the tally counter.
    pub fn peek(&self) -> usize {
        self.tally.load(Ordering::Relaxed)
    }
}

/// A lazy tally value. Each object of this type has an unique tally value that is assigned
/// at the first call to [LazyTally::get].
#[repr(C)]
pub struct LazyTally {
    value: AtomicUsize,
    once: Once,
}

impl LazyTally {
    /// Creates a new [LazyTally] object. This object can store a unique id which is assigned to it
    /// at the first call to [LazyTally::get].
    pub const fn new() -> Self {
        LazyTally {
            value: AtomicUsize::new(0),
            once: Once::new(),
        }
    }

    /// Gets the tally for this object. Subsequent calls to this function will
    /// return the same value on this object. The guarantee is that different
    /// objects will return different values.
    pub fn get(&self) -> usize {
        let mut val = self.value.load(Ordering::Relaxed);
        self.once.call_once(|| {
            val = crate::next();
            self.value.store(val, Ordering::Relaxed);
        });
        val
    }
}
impl Default for LazyTally {
    fn default() -> Self {
        Self::new()
    }
}