Struct Ulid

pub struct Ulid;

A thread-local ULID generator with monotonic and non-monotonic modes.

Provides fast, per-thread ULID generation using a shared monotonic clock and thread-local RNG. Monotonic overflows are handled with configurable Backoff strategies.

Requires the ulid and thread_local features.

Implementations

impl Ulid

pub fn new_ulid() -> ULID

Generates a non-monotonic ULID that is always random, even when generated within the same millisecond.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::Ulid;
    let id = Ulid::new_ulid();
}

pub fn new_mono_ulid() -> ULID

Generates a monotonic ULID using Backoff::Yield as the overflow strategy.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::Ulid;
    let id = Ulid::new_mono_ulid();
}

pub fn with_mono_backoff(strategy: Backoff) -> ULID

Generates a monotonic ULID using the given Backoff strategy to handle overflow.

If the generator exhausts available entropy within the same millisecond, the backoff strategy determines how it waits before retrying.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::{Ulid, Backoff};
    let id = Ulid::with_mono_backoff(Backoff::Spin);
}

pub fn from_timestamp(timestamp: <ULID as Id>::Ty) -> ULID

Creates a ULID from a given millisecond timestamp.

Random bits are generated using the thread-local RNG. The resulting ID is not guaranteed to be monotonic.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::Ulid;
    let id = Ulid::from_timestamp(1_694_201_234_000);
}

pub fn from_timestamp_and_rand<R>(timestamp: <ULID as Id>::Ty, rng: &R) -> ULID

where R: RandSource<<ULID as Id>::Ty>,

Creates a ULID from a given millisecond timestamp and a custom RNG.

Useful in deterministic or testable scenarios where a specific random source is preferred.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::{Ulid, ThreadRandom};
    let id = Ulid::from_timestamp_and_rand(0, &ThreadRandom);
}

pub fn from_datetime(datetime: SystemTime) -> ULID

Creates a ULID from a SystemTime.

This is a convenience wrapper over Ulid::from_timestamp that extracts the Unix timestamp in milliseconds.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::Ulid;
    let id = Ulid::from_datetime(std::time::SystemTime::now());
}

pub fn from_datetime_and_rand<R>(datetime: SystemTime, rng: &R) -> ULID

where R: RandSource<<ULID as Id>::Ty>,

Creates a ULID from a SystemTime and a custom RNG.

Example

#[cfg(all(feature = "ulid", feature = "thread_local"))]
{
    use ferroid::{Ulid, ThreadRandom};
    let now = std::time::SystemTime::now();
    let id = Ulid::from_datetime_and_rand(now, &ThreadRandom);
}