ferroid 2.0.0

High-performance ULID and Snowflake-style IDs. Unique, monotonic, and lexicographically sortable IDs optimized for low-latency services and async workloads.
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

use core::fmt;

use crate::{
    generator::{Poll, Result},
    id::SnowflakeId,
    time::TimeSource,
};

/// A minimal interface for generating Snowflake IDs.
pub trait SnowflakeGenerator<ID, T>
where
    ID: SnowflakeId,
    T: TimeSource<ID::Ty>,
{
    /// The error type returned by [`SnowflakeGenerator::try_next_id`].
    type Err: fmt::Debug;

    /// Creates a new generator.
    fn new(machine_id: ID::Ty, time: T) -> Self;

    /// Generates the next available ID.
    ///
    /// This is the infallible counterpart to
    /// [`SnowflakeGenerator::try_next_id`]. The returned [`Poll`] contains
    /// either:
    /// - the newly generated ID, or
    /// - a duration to yield/sleep if the generator must wait for the time
    ///   source to advance.
    fn next_id(&self, f: impl FnMut(ID::Ty)) -> ID
    where
        Self::Err: Into<core::convert::Infallible>,
    {
        match self.try_next_id(f) {
            Ok(id) => id,
            Err(e) => {
                #[allow(unreachable_code)]
                // `into()` satisfies the trait bound at compile time.
                match e.into() {}
            }
        }
    }

    /// Generates the next available ID with fallible error handling.
    ///
    /// The returned [`Poll`] contains either:
    /// - the newly generated ID, or
    /// - a duration to yield/sleep if the generator must wait for the time
    ///   source to advance.
    ///
    /// # Errors
    ///
    /// May return an error if the underlying implementation uses a lock and it
    /// is poisoned.
    fn try_next_id(&self, f: impl FnMut(ID::Ty)) -> Result<ID, Self::Err>;

    /// Attempts to generate the next available ID.
    ///
    /// This is the infallible counterpart to
    /// [`SnowflakeGenerator::try_poll_id`]. The returned [`Poll`] contains
    /// either:
    /// - the newly generated ID, or
    /// - a duration to yield/sleep if the generator must wait for the time
    ///   source to advance.
    fn poll_id(&self) -> Poll<ID>
    where
        Self::Err: Into<core::convert::Infallible>,
    {
        match self.try_poll_id() {
            Ok(status) => status,
            Err(e) => {
                #[allow(unreachable_code)]
                // `into()` satisfies the trait bound at compile time.
                match e.into() {}
            }
        }
    }

    /// Attempts to generate the next available ID with fallible error handling.
    ///
    /// The returned [`Poll`] contains either:
    /// - the newly generated ID, or
    /// - a duration to yield/sleep if the generator must wait for the time
    ///   source to advance.
    ///
    /// # Errors
    ///
    /// May return an error if the underlying implementation uses a lock and it
    /// is poisoned.
    fn try_poll_id(&self) -> Result<Poll<ID>, Self::Err>;
}