pub struct UlidGenerator { /* private fields */ }Expand description
Monotonic ULIDs for one explicitly owned issuance stream.
Supply the timestamp captured for the write operation and fresh host-provided randomness. This generator never reads a clock, seeds an RNG or makes a call. Equal/backward timestamps retain the last timestamp and increment its suffix. That logical timestamp can differ from the operation’s managed timestamps.
Successful issuance consumes an ID even if a later database batch is refused; gaps are permitted. An IC trap reverts in-canister state in that execution. The host must preserve the last issued ID and restore it after upgrades if monotonicity must continue. Restoring an older checkpoint or starting another stream can repeat IDs. Independent streams need independently provisioned randomness; neither global uniqueness nor secret-token suitability is promised.
Implementations§
Source§impl UlidGenerator
impl UlidGenerator
Sourcepub const fn new() -> Self
pub const fn new() -> Self
Start a new stream with no preceding identifier, including at Unix epoch.
Sourcepub const fn resume_after(last: Ulid) -> Self
pub const fn resume_after(last: Ulid) -> Self
Continue after the host’s authoritative last issued identifier. Restoring stale state can repeat identifiers; the database does not own this checkpoint.
Sourcepub const fn last(&self) -> Option<Ulid>
pub const fn last(&self) -> Option<Ulid>
The last successfully issued identifier, suitable for a host-owned checkpoint.
Sourcepub fn generate(
&mut self,
timestamp: Timestamp,
randomness: [u8; 10],
) -> Result<Ulid, UlidGenerationError>
pub fn generate( &mut self, timestamp: Timestamp, randomness: [u8; 10], ) -> Result<Ulid, UlidGenerationError>
Issue an ID at the operation’s timestamp using an explicit 80-bit random suffix.
Randomness is used only for the first ID or a timestamp newer than the last issued timestamp. The caller must obtain it before the synchronous write boundary; it may use an already seeded host stream without an inter-canister call.
§Errors
Rejects negative or greater-than-48-bit millisecond timestamps. If the suffix is exhausted at an equal/backward time, refuses without advancing time or wrapping the suffix. Every error preserves the previous state.