Struct LockMonoUlidGenerator

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

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

This generator wraps the Ulid state in an Arc<Mutex<_>>, allowing safe shared use across threads.

Features

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

Recommended When

• You’re in a multi-threaded environment
• You need require monotonically increasing IDs (ID generated within the same millisecond increment a sequence counter)

See Also

• BasicUlidGenerator
• BasicMonoUlidGenerator

Implementations

impl<ID, T, R> LockMonoUlidGenerator<ID, T, R>

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

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

Creates a new LockMonoUlidGenerator 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 = "ulid"))]
{
    use ferroid::{LockMonoUlidGenerator, IdGenStatus, ULID, MonotonicClock, ThreadRandom};
     
    let generator = LockMonoUlidGenerator::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 from_components( timestamp: ID::Ty, random: ID::Ty, clock: T, rng: R, ) -> Self

Creates a new ID generator from explicit component values.

This constructor is primarily useful for advanced use cases such as restoring state from persistent storage or controlling the starting point of the generator manually.

Parameters

• timestamp: The initial timestamp component (usually in milliseconds)
• machine_id: The machine or worker identifier
• sequence: The initial sequence number
• clock: A TimeSource implementation used to fetch the current time

Returns

A new generator instance preloaded with the given state.

⚠️ Note

In typical use cases, you should prefer Self::new to let the generator initialize itself from the current time.

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

Panics if the lock is poisoned. For explicitly fallible behavior, use Self::try_next_id instead.

Example

#[cfg(all(feature = "std", feature = "ulid"))]
{
    use ferroid::{LockMonoUlidGenerator, IdGenStatus, ULID, MonotonicClock, ThreadRandom};
     
    let generator = LockMonoUlidGenerator::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>, Error<Infallible>>

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(e): the lock was poisoned

Errors

• Returns an error if the underlying lock has been poisoned.

Example

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

    let generator = BasicMonoUlidGenerator::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(e) => panic!("Generator error: {}", e),
        }
    };
}

Trait Implementations

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

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

type Err = Error

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.