libxid

August 9, 2023 · View on GitHub

A globally unique id generator.

This is a c++ implementation of the Golang package found at: https://github.com/rs/xid

Xid uses MongoDB Object ID algorighm¹ to generate globally unique ids with base32 serialzation to produce shorter strings.

Binary representation

+---+----+----+----+----+----+----+----+----+----+-----+-----+
| 0 |  1 |  2 |  3 |  4 |  5 |  6 |  7 |  8 |  9 |  10 |  11 |
+---+----+----+----+----+----+----+----+----+----+-----+-----+
 \----- time -----/ \ machine id / \- pid -/ \--- counter ---/

4-byte value representing the seconds since the Unix epoch,
3-byte machine identifier,
2-byte process id, and
3-byte counter, starting with a random value.

The binary representation of the id is compatible with MongoDB's 12 bytes Object IDs. The string representation is using base32hex (w/o padding)² for better space efficiency when stored in string form (20 bytes). The hex variant of base32 is used to retain the sortable property of the id.

Features

Size: 12 bytes (96 bits), smaller than UUID, larger than Twitter Snowflake³
Base32hex encoded by default (20 chars when transported as printable string, still sortable)
Configuration free: there is no need to set a unique machine and/or data center id
K-ordered
Embedded time with 1 second precision
Unicity guaranteed for 16,777,216 (24 bits) unique ids per second and per host/process
Lock-free (unlike UUIDv1 and v2)

Comparison

Name	Binary Size	String Size	Features
UUID	16 bytes	36 chars	configuration free, not sortable
shortuuid	16 bytes	22 chars	configuration free, not sortable
Snowflake	8 bytes	up to 20 chars	needs machine/DC configuration, needs central server, sortable
MongoID	12 bytes	24 chars	configuration free, sortable
xid	12 bytes	20 chars	configuration free, sortable

Install

CMake

include(FetchContent)

#libxid
FetchContent_Declare(libxid
  URL      https://github.com/uatuko/libxid/archive/refs/tags/v0.1.0.tar.gz
  URL_HASH SHA256=31589bb5274c9d25a8b6c49ee04a6c76151f10082e7feb13314be02a4b2d58c8
)
FetchContent_MakeAvailable(libxid)

target_link_libraries(<target>
  PRIVATE
    libxid::xid
)

Usage

#include <xid/xid.h>

auto id = xid::next(); // generate the next id
std::string s = xid::next(); // generate the next id and convert it to a string

// Get embedded info
auto id = xid::next();

id.time();
id.machine();
id.pid();
id.counter();

// Decode id strings
auto id = xid::id("cc0a2mn6i1e6brmdbip0");
auto bytes = xid::id::decode("cc0aar76i1e6jr6no620");