Struct SnowflakeIdGenerator

Source

pub struct SnowflakeIdGenerator { /* private fields */ }

Expand description

A Snowflake ID generator with a configurable BitLayout.

§Thread safety

SnowflakeIdGenerator is not Send + Sync by itself because its internal state is mutated on every call. Wrap it in a Mutex / RwLock when sharing across threads.

§Example — default layout

use snowflake_gen::SnowflakeIdGenerator;

let mut idgen = SnowflakeIdGenerator::new(1, 1).unwrap();
let id = idgen.generate().unwrap();
assert!(id > 0);

Implementations§

Source §

impl SnowflakeIdGenerator

Source

pub fn new(machine_id: i64, node_id: i64) -> Result<Self, SnowflakeError>

Constructs a generator using the UNIX epoch and the default BitLayout.

use snowflake_gen::SnowflakeIdGenerator;

let mut idgen = SnowflakeIdGenerator::new(1, 1).unwrap();

Source

pub fn with_epoch( machine_id: i64, node_id: i64, epoch: SystemTime, ) -> Result<Self, SnowflakeError>

Constructs a generator using a custom epoch and the default BitLayout.

use std::time::{Duration, UNIX_EPOCH};
use snowflake_gen::SnowflakeIdGenerator;

// Discord epoch: 1 January 2015 00:00:00 UTC
let discord_epoch = UNIX_EPOCH + Duration::from_millis(1_420_070_400_000);
let mut idgen = SnowflakeIdGenerator::with_epoch(1, 1, discord_epoch).unwrap();

Source

pub fn with_layout( machine_id: i64, node_id: i64, layout: BitLayout, ) -> Result<Self, SnowflakeError>

Constructs a generator with a fully custom BitLayout and UNIX epoch.

use snowflake_gen::{BitLayout, SnowflakeIdGenerator};

let layout = BitLayout::new(38, 8, 7, 10).unwrap();
let mut idgen = SnowflakeIdGenerator::with_layout(1, 1, layout).unwrap();

Source

pub fn with_layout_and_epoch( machine_id: i64, node_id: i64, layout: BitLayout, epoch: SystemTime, ) -> Result<Self, SnowflakeError>

Constructs a generator with a fully custom BitLayout and epoch.

§Errors

SnowflakeError::MachineIdOutOfRange if machine_id > layout.max_machine_id().
SnowflakeError::NodeIdOutOfRange if node_id > layout.max_node_id().
SnowflakeError::ClockBeforeEpoch if the current time is before epoch.

Source §

impl SnowflakeIdGenerator

Source

pub fn generate(&mut self) -> Result<i64, SnowflakeError>

Generates the next ID, blocking until the next millisecond if the sequence counter wraps.

use snowflake_gen::SnowflakeIdGenerator;

let mut idgen = SnowflakeIdGenerator::new(1, 1).unwrap();
let id = idgen.generate().unwrap();
assert!(id > 0);

Source

pub fn real_time_generate(&mut self) -> Result<i64, SnowflakeError>

Generates the next ID, always reading the current clock.

Source

pub fn lazy_generate(&mut self) -> i64

Generates the next ID without reading the system clock.

Instead of a syscall, lazy_generate synthetically increments last_time_millis whenever the sequence counter wraps. This makes it the fastest generation mode but comes with an important constraint:

Do not mix lazy_generate with generate or real_time_generate on the same generator instance. Because lazy_generate can advance last_time_millis ahead of the real clock, a subsequent clock-based call may produce a timestamp that lazy_generate already used, resulting in duplicate IDs.

SnowflakeIdBucket uses lazy_generate internally on a dedicated generator that is never exposed for clock-based calls, so it is safe.

Source §

impl SnowflakeIdGenerator

Source

pub fn decompose(&self, id: i64) -> SnowflakeComponents

Decodes a previously generated ID back into its constituent fields.

use snowflake_gen::SnowflakeIdGenerator;

let mut idgen = SnowflakeIdGenerator::new(3, 7).unwrap();
let id = idgen.generate().unwrap();
let parts = idgen.decompose(id);

assert_eq!(parts.machine_id, 3);
assert_eq!(parts.node_id, 7);