Struct BasicUlidGenerator

pub struct BasicUlidGenerator<ID, T, R>
where
    ID: UlidId,
    T: TimeSource<ID::Ty>,
    R: RandSource<ID::Ty>,
{ /* private fields */ }

A non-monotonic ULID-style ID generator suitable for multi-threaded environments.

This generator is lightweight and fast, but has a higher collision probabiliy than it’s monotonic counterpart.

Features

• ✅ Thread-safe
• ✅ Probabilistically unique (no coordination required)
• ✅ Time-ordered (not monotonically increasing, random per millisecond)

Recommended When

• You’re in a single or multi-threaded environment
• You require purely random IDs (even within the same millisecond)

See Also

• BasicMonoUlidGenerator
• LockMonoUlidGenerator

Implementations

impl<ID, T, R> BasicUlidGenerator<ID, T, R>

where ID: UlidId, T: TimeSource<ID::Ty>, R: RandSource<ID::Ty>,

pub const fn new(clock: T, rng: R) -> Self

Creates a new BasicUlidGenerator with the provided time source and RNG.

Parameters

• clock: A TimeSource used to retrieve the current timestamp
• rng: A RandSource used to generate random bits

Returns

A ready-to-use ULID generator suitable for producing unique, sortable IDs.

Example

#[cfg(all(feature = "std", feature = "alloc", feature = "ulid"))]
{
    use ferroid::{BasicUlidGenerator, IdGenStatus, ULID, MonotonicClock, ThreadRandom};
     
    let generator = BasicUlidGenerator::new(MonotonicClock::default(), ThreadRandom::default());

    let id: ULID = loop {
        match generator.next_id() {
            IdGenStatus::Ready { id } => break id,
            IdGenStatus::Pending { .. } => core::hint::spin_loop(),
        }
    };
}

pub fn next_id(&self) -> IdGenStatus<ID>

Generates a new ULID.

Internally calls Self::try_next_id and unwraps the result. This method will panic on error, so prefer the fallible version if you want explicit control over error handling.

Panics

This method currently has no fallible code paths, but may panic if an internal error occurs in future implementations. For explicitly fallible behavior, use Self::try_next_id instead.

Example

#[cfg(all(feature = "std", feature = "alloc", feature = "ulid"))]
{
    use ferroid::{BasicUlidGenerator, IdGenStatus, ULID, MonotonicClock, ThreadRandom};
     
    let generator = BasicUlidGenerator::new(MonotonicClock::default(), ThreadRandom::default());

    let id: ULID = loop {
        match generator.next_id() {
            IdGenStatus::Ready { id } => break id,
            IdGenStatus::Pending { .. } => std::thread::yield_now(),
        }
    };
}

pub fn try_next_id(&self) -> Result<IdGenStatus<ID>>

Attempts to generate a new ULID with fallible error handling.

Combines the current timestamp with a freshly generated random value to produce a unique identifier. Returns IdGenStatus::Ready on success.

Returns

• Ok(IdGenStatus::Ready { id }): A new ID is available
• Ok(IdGenStatus::Pending { yield_for }): The time to wait (in milliseconds) before trying again
• Err(_): infallible for this generator

Errors

• This method currently does not return any errors and always returns Ok. It is marked as fallible to allow for future extensibility

Example

#[cfg(all(feature = "std", feature = "alloc", feature = "ulid"))]
{
    use ferroid::{BasicUlidGenerator, IdGenStatus, ULID, ToU64, MonotonicClock, ThreadRandom};

    let generator = BasicUlidGenerator::new(MonotonicClock::default(), ThreadRandom::default());

    // Attempt to generate a new ID
    let id: ULID = loop {
        match generator.try_next_id() {
            Ok(IdGenStatus::Ready { id }) => break id,
            Ok(IdGenStatus::Pending { yield_for }) => {
                std::thread::sleep(core::time::Duration::from_millis(yield_for.to_u64()));
            }
            Err(_) => unreachable!(),
        }
    };
}

Trait Implementations

impl<ID, T, R> UlidGenerator<ID, T, R> for BasicUlidGenerator<ID, T, R>

where ID: UlidId, T: TimeSource<ID::Ty>, R: RandSource<ID::Ty>,

type Err = Infallible

fn new(clock: T, rng: R) -> Self

fn next_id(&self) -> IdGenStatus<ID>

Returns the next available ID

fn try_next_id(&self) -> Result<IdGenStatus<ID>, Self::Err>

A fallible version of Self::next_id that returns a Result.