Crate atomic_id

atomic-id

A high-performance, thread-safe, and globally unique ID generator. Inspired by Snowflake, it supports multiple bit-widths (24, 32, 64, 128, 256) and encodings, making it suitable for a wide range of applications from database keys to distributed service identifiers.

Features

• Multiple Bit-Widths: Generate IDs of 24, 32, 64, 128, or 256 bits.
• Thread-Safe: Uses atomic operations to guarantee uniqueness across threads.
• Distributed-System Ready: Incorporates node and shard IDs for global uniqueness.
• Customizable Epoch: Set a custom epoch for timestamp-based generation.
• Flexible Encodings: Output IDs in base36, base58, base91, or hexadecimal.
• High Performance: Optimized for low-latency ID generation in high-throughput systems.

Feature Flags

• short: Enables support for 24-bit and 32-bit IDs (x24, x32). This feature is disabled by default to keep the library lightweight.

Quick Start

Add atomic-id to your Cargo.toml. To use 24-bit or 32-bit IDs, enable the short feature.

[dependencies]
atomic-id = { version = "0.1", features = ["short"] } # Replace with the latest version

Generating a 64-bit ID

use atomic_id::{AtomicId, x64};

// Generate a new base36-encoded 64-bit ID.
let id = AtomicId::<x64>::new();
println!("64-bit ID: {}", id);

ID Structure

The library generates IDs with different structures depending on the bit-width:

• 24-bit: 24-bit sequence
• 32-bit: 8-bit thread ID | 24-bit sequence
• 64-bit: 20-bit timestamp | 12-bit node ID | 8-bit shard ID | 8-bit thread ID | 16-bit sequence
• 128-bit & 256-bit: More complex structures with higher entropy from timestamps, nanoseconds, and sequences.

Advanced Usage

Custom Epoch

For timestamp-based IDs (64, 128, 256-bit), you can set a custom epoch.

use atomic_id::AtomicOption;
// Set a custom epoch to `2024-01-01 00:00:00 UTC` in milliseconds.
AtomicOption::epoch(1704067200000);

Different Encodings

use atomic_id::{AtomicId, x64};

let id_base58 = AtomicId::<x64>::base58();
let id_hex = AtomicId::<x64>::hex();

println!("Base58: {}", id_base58);
println!("Hex:    {}", id_hex);

Structs

AtomicId

The main entry point for generating atomic IDs of a specific bit width.

AtomicOption

Provides methods for configuring global settings for atomic-id.

IdGenerator

The core generator struct for producing unique IDs.

Constants

x64

Constant for 64-bit mode.

x128

Constant for 128-bit mode.

x256

Constant for 256-bit mode.