beakid 0.2.5

Snowflake-like 64-bit unique ID generator with PostgreSQL BIGINT-friendly i64 IDs.
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
112
113
114
115
116
117
118
119
120
121
122

#![doc = include_str!("../README.md")]
#![warn(missing_docs)]

//! Public API for BeakId.

pub mod background;
pub mod beakid;
pub mod config;
pub mod error;
pub mod generator;
pub mod macros;

use std::sync::{Arc, OnceLock};

pub use background::BackgroundHandle;
pub use beakid::BeakId;
pub use config::Config;
pub use error::{BeakIdError, Result};
pub use generator::Generator;
pub use tokistamp::Timestamp;

static GENERATOR: OnceLock<Result<Arc<Generator>>> = OnceLock::new();
static BACKGROUND: OnceLock<BackgroundHandle> = OnceLock::new();

fn singleton() -> Result<Arc<Generator>> {
    GENERATOR
        .get_or_init(|| {
            Config::from_env()
                .and_then(Generator::from_config)
                .map(Arc::new)
        })
        .as_ref()
        .map(Arc::clone)
        .map_err(Clone::clone)
}

/// Returns the next process-wide BeakId.
///
/// The global generator is initialized lazily on first use from environment
/// variables. Use [`try_next_id`] when configuration errors should be handled
/// instead of panicking.
///
/// # Panics
///
/// Panics if `BEAKID_EPOCH` is missing or invalid, if `BEAKID_WORKER_ID` is
/// invalid, or if the system clock is before the configured epoch.
///
/// # Examples
///
/// ```no_run
/// # unsafe {
/// std::env::set_var("BEAKID_EPOCH", "2025-01-01T00:00:00Z");
/// std::env::set_var("BEAKID_WORKER_ID", "42");
/// # }
/// let id = beakid::next_id();
/// assert!(id.as_i64() >= 0);
/// ```
#[must_use]
pub fn next_id() -> BeakId {
    try_next_id().expect("failed to generate BeakId")
}

/// Returns the next process-wide BeakId, reporting configuration and clock
/// errors explicitly.
///
/// # Examples
///
/// ```no_run
/// # unsafe {
/// std::env::set_var("BEAKID_EPOCH", "2025-01-01T00:00:00Z");
/// # }
/// let id = beakid::try_next_id()?;
/// # Ok::<(), beakid::BeakIdError>(())
/// ```
pub fn try_next_id() -> Result<BeakId> {
    singleton()?.next_id()
}

/// Returns the absolute creation timestamp encoded in a BeakId generated with
/// the singleton epoch.
///
/// This initializes the singleton if needed, so `BEAKID_EPOCH` must be present
/// and valid.
///
/// # Examples
///
/// ```no_run
/// # unsafe {
/// std::env::set_var("BEAKID_EPOCH", "2025-01-01T00:00:00Z");
/// # }
/// let id = beakid::try_next_id()?;
/// let created_at = beakid::timestamp(id)?;
/// # Ok::<(), beakid::BeakIdError>(())
/// ```
pub fn timestamp(id: BeakId) -> Result<Timestamp> {
    singleton()?.timestamp(id)
}

/// Starts the singleton background updater on a standard OS thread.
///
/// The updater refreshes the real 100ms time-window hint roughly every 30ms.
/// Calling this function more than once is harmless. If this function is not
/// called, ID generation still works at normal rates, but extremely high
/// sequence overflow workloads can return [`BeakIdError::Blocked`] until real
/// time advances.
///
/// # Examples
///
/// ```no_run
/// # unsafe {
/// std::env::set_var("BEAKID_EPOCH", "2025-01-01T00:00:00Z");
/// # }
/// beakid::start_background()?;
/// let id = beakid::try_next_id()?;
/// # Ok::<(), beakid::BeakIdError>(())
/// ```
pub fn start_background() -> Result<()> {
    let generator = singleton()?;
    let handle = background::start_thread(generator)?;
    let _ = BACKGROUND.set(handle);
    Ok(())
}