SCRU128: Sortable, Clock and Random number-based Unique identifier. More...

#include <stdint.h>

Data Structures
struct	Scru128Generator
	Represents a SCRU128 ID generator that encapsulates the monotonic counter and other internal states. More...

Macros
#define	SCRU128_LEN (16)
	The size in bytes of a SCRU128 ID in the binary representation (16 bytes).

#define	SCRU128_STR_LEN (26)
	The size in bytes of a SCRU128 ID in the string representation (25 digits + NUL).

Status codes returned by generator functions
#define	SCRU128_GENERATOR_STATUS_NEW_TIMESTAMP (1)
	Indicates that the latest `timestamp` was used because it was greater than the previous one.

#define	SCRU128_GENERATOR_STATUS_COUNTER_LO_INC (2)
	Indicates that `counter_lo` was incremented because the latest `timestamp` was no greater than the previous one.

#define	SCRU128_GENERATOR_STATUS_COUNTER_HI_INC (3)
	Indicates that `counter_hi` was incremented because `counter_lo` reached its maximum value.

#define	SCRU128_GENERATOR_STATUS_TIMESTAMP_INC (4)
	Indicates that the previous `timestamp` was incremented because `counter_hi` reached its maximum value.

#define	SCRU128_GENERATOR_STATUS_ROLLBACK_RESET (5)
	Indicates that the generator was reinitialized and the monotonic order of generated IDs was broken because the latest `timestamp` was significantly smaller than the previous one.

#define	SCRU128_GENERATOR_STATUS_ERROR (-1)
	Indicates that the previous generation failed.

#define	SCRU128_GENERATOR_STATUS_ROLLBACK_ABORT (-2)
	Indicates that the previous generation was aborted because the latest `timestamp` was significantly smaller than the previous one.

Typedefs
typedef struct Scru128Generator	Scru128Generator
	Represents a SCRU128 ID generator that encapsulates the monotonic counter and other internal states.

Functions
Identifier-related functions
This library represents a binary SCRU128 ID as a 16-byte `uint8_t` array containing a 128-bit unsigned integer in the big-endian (network) byte order.
static int	scru128_from_fields (uint8_t *id_out, uint64_t timestamp, uint32_t counter_hi, uint32_t counter_lo, uint32_t entropy)
	Creates a SCRU128 ID from field values.

static void	scru128_copy (uint8_t id_dst, const uint8_t id_src)
	Copies a SCRU128 ID from `id_src` to `id_dst`.

static int	scru128_from_str (uint8_t id_out, const char str)
	Creates a SCRU128 ID from a 25-digit string representation.

static uint64_t	scru128_timestamp (const uint8_t *id)
	Returns the 48-bit `timestamp` field value of a SCRU128 ID.

static uint32_t	scru128_counter_hi (const uint8_t *id)
	Returns the 24-bit `counter_hi` field value of a SCRU128 ID.

static uint32_t	scru128_counter_lo (const uint8_t *id)
	Returns the 24-bit `counter_lo` field value of a SCRU128 ID.

static uint32_t	scru128_entropy (const uint8_t *id)
	Returns the 32-bit `entropy` field value of a SCRU128 ID.

static void	scru128_to_str (const uint8_t id, char str_out)
	Returns the 25-digit canonical string representation of a SCRU128 ID.

static int	scru128_compare (const uint8_t id_lft, const uint8_t id_rgt)
	Returns a negative integer, zero, or positive integer if `id_lft` is less than, equal to, or greater than `id_rgt`, respectively.

Generator-related functions
static void	scru128_generator_init (Scru128Generator *g)
	Initializes a generator struct `g`.

static int8_t	scru128_generate_or_abort_core (Scru128Generator g, uint8_t id_out, uint64_t timestamp, uint32_t(*arc4random)(void), uint64_t rollback_allowance)
	Generates a new SCRU128 ID with the given `timestamp` and random number generator, or returns an error upon significant timestamp rollback.

static int8_t	scru128_generate_or_reset_core (Scru128Generator g, uint8_t id_out, uint64_t timestamp, uint32_t(*arc4random)(void), uint64_t rollback_allowance)
	Generates a new SCRU128 ID with the given `timestamp` and random number generator, or resets the generator upon significant timestamp rollback.

High-level generator APIs that require platform integration
int	scru128_generate (Scru128Generator g, uint8_t id_out)
	Generates a new SCRU128 ID from the current `timestamp`.

static int	scru128_generate_string (Scru128Generator g, char str_out)
	Generates a new SCRU128 ID encoded in the 25-digit canonical string representation.

Detailed Description

SCRU128: Sortable, Clock and Random number-based Unique identifier.

Version: v0.4.3

Copyright: Licensed under the Apache License, Version 2.0

See also: https://github.com/scru128/c

Typedef Documentation

◆ Scru128Generator

typedef struct Scru128Generator Scru128Generator

Represents a SCRU128 ID generator that encapsulates the monotonic counter and other internal states.

A new generator must be initialized by scru128_generator_init() before use.

Function Documentation

◆ scru128_compare()

static int scru128_compare	(	const uint8_t *	id_lft,
		const uint8_t *	id_rgt
	)

inlinestatic

Returns a negative integer, zero, or positive integer if id_lft is less than, equal to, or greater than id_rgt, respectively.

Parameters

id_lft	A 16-byte big-endian byte array that represents a SCRU128 ID.
id_rgt	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_copy()

static void scru128_copy	(	uint8_t *	id_dst,
		const uint8_t *	id_src
	)

inlinestatic

Copies a SCRU128 ID from id_src to id_dst.

Parameters

id_dst	A 16-byte byte array where the copied SCRU128 ID is stored.
id_src	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_counter_hi()

static uint32_t scru128_counter_hi ( const uint8_t * id )

inlinestatic

Returns the 24-bit counter_hi field value of a SCRU128 ID.

Parameters

id	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_counter_lo()

static uint32_t scru128_counter_lo ( const uint8_t * id )

inlinestatic

Returns the 24-bit counter_lo field value of a SCRU128 ID.

Parameters

id	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_entropy()

static uint32_t scru128_entropy ( const uint8_t * id )

inlinestatic

Returns the 32-bit entropy field value of a SCRU128 ID.

Parameters

id	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_from_fields()

static int scru128_from_fields	(	uint8_t *	id_out,
		uint64_t	timestamp,
		uint32_t	counter_hi,
		uint32_t	counter_lo,
		uint32_t	entropy
	)

inlinestatic

Creates a SCRU128 ID from field values.

Parameters

id_out	A 16-byte byte array where the created SCRU128 ID is stored.
timestamp	A 48-bit `timestamp` field value.
counter_hi	A 24-bit `counter_hi` field value.
counter_lo	A 24-bit `counter_lo` field value.
entropy	A 32-bit `entropy` field value.

Returns: Zero on success or a non-zero integer if any argument is out of the value range of the field.

◆ scru128_from_str()

static int scru128_from_str	(	uint8_t *	id_out,
		const char *	str
	)

inlinestatic

Creates a SCRU128 ID from a 25-digit string representation.

Parameters

id_out	A 16-byte byte array where the created SCRU128 ID is stored.
str	A null-terminated character array containing the 25-digit string representation.

Returns: Zero on success or a non-zero integer if str is not a valid string representation.

◆ scru128_generate()

int scru128_generate	(	Scru128Generator *	g,
		uint8_t *	id_out
	)

Generates a new SCRU128 ID from the current timestamp.

Parameters

g	A generator state object used to generate an ID.
id_out	A 16-byte byte array where the generated SCRU128 ID is stored.

Returns: One of SCRU128_GENERATOR_STATUS_* codes that describes the characteristics of generated ID. A negative return code reports an error.

Note: This single-file library does not provide a concrete implementation of this function, so users have to implement it to enable high-level generator APIs (if necessary) by integrating the low-level generator primitives provided by the library with the real-time clock and random number generator available in the system.

Attention: The thread-safety of this function is implementation-dependent, but it is usually NOT thread-safe. The generator g should be protected from concurrent accesses using a mutex or other synchronization mechanism to avoid race conditions.

◆ scru128_generate_or_abort_core()

static int8_t scru128_generate_or_abort_core	(	Scru128Generator *	g,
		uint8_t *	id_out,
		uint64_t	timestamp,
		uint32_t(*)(void)	arc4random,
		uint64_t	rollback_allowance
	)

inlinestatic

Generates a new SCRU128 ID with the given timestamp and random number generator, or returns an error upon significant timestamp rollback.

This function returns a monotonically increasing ID by reusing the previous timestamp even if the one provided is smaller than the immediately preceding ID's. However, when such a clock rollback is considered significant (by more than rollback_allowance milliseconds), this function aborts and returns SCRU128_GENERATOR_STATUS_ROLLBACK_ABORT immediately.

See scru128_generate_or_reset_core() for the other mode of generation.

Parameters

g	A generator state object used to generate an ID.
id_out	A 16-byte byte array where the generated SCRU128 ID is stored.
timestamp	A 48-bit `timestamp` field value.
arc4random	A function pointer to `arc4random()` or a compatible function that returns a (cryptographically strong) random number in the range of 32-bit unsigned integer.
rollback_allowance	The amount of `timestamp` rollback that is considered significant. A suggested value is `10000` (milliseconds).

Returns: One of SCRU128_GENERATOR_STATUS_* codes that describes the characteristics of generated ID. A negative return code reports an error.

Attention: This function is NOT thread-safe. The generator g should be protected from concurrent accesses using a mutex or other synchronization mechanism to avoid race conditions.

◆ scru128_generate_or_reset_core()

static int8_t scru128_generate_or_reset_core	(	Scru128Generator *	g,
		uint8_t *	id_out,
		uint64_t	timestamp,
		uint32_t(*)(void)	arc4random,
		uint64_t	rollback_allowance
	)

inlinestatic

Generates a new SCRU128 ID with the given timestamp and random number generator, or resets the generator upon significant timestamp rollback.

This function returns a monotonically increasing ID by reusing the previous timestamp even if the one provided is smaller than the immediately preceding ID's. However, when such a clock rollback is considered significant (by more than rollback_allowance milliseconds), this function resets the generator and returns a new ID based on the given timestamp, breaking the increasing order of IDs.

See scru128_generate_or_abort_core() for the other mode of generation.

Parameters

g	A generator state object used to generate an ID.
id_out	A 16-byte byte array where the generated SCRU128 ID is stored.
timestamp	A 48-bit `timestamp` field value.
arc4random	A function pointer to `arc4random()` or a compatible function that returns a (cryptographically strong) random number in the range of 32-bit unsigned integer.
rollback_allowance	The amount of `timestamp` rollback that is considered significant. A suggested value is `10000` (milliseconds).

Returns: One of SCRU128_GENERATOR_STATUS_* codes that describes the characteristics of generated ID. A negative return code reports an error.

Attention: This function is NOT thread-safe. The generator g should be protected from concurrent accesses using a mutex or other synchronization mechanism to avoid race conditions.

◆ scru128_generate_string()

static int scru128_generate_string	(	Scru128Generator *	g,
		char *	str_out
	)

inlinestatic

Generates a new SCRU128 ID encoded in the 25-digit canonical string representation.

Parameters

g	A generator state object used to generate an ID.
str_out	A 26-byte character array where the returned string is stored. The returned array is a 26-byte null-terminated string consisting of 25 `[0-9a-z]` characters and null.

Returns: The return value of scru128_generate().

Note: Provide a concrete implementation of scru128_generate() to enable this function.

Attention: See scru128_generate() for the thread-safety consideration.

◆ scru128_timestamp()

static uint64_t scru128_timestamp ( const uint8_t * id )

inlinestatic

Returns the 48-bit timestamp field value of a SCRU128 ID.

Parameters

id	A 16-byte big-endian byte array that represents a SCRU128 ID.

◆ scru128_to_str()

static void scru128_to_str	(	const uint8_t *	id,
		char *	str_out
	)

inlinestatic

Returns the 25-digit canonical string representation of a SCRU128 ID.

Parameters

id	A 16-byte big-endian byte array that represents a SCRU128 ID.
str_out	A 26-byte character array where the returned string is stored. The returned array is a 26-byte null-terminated string consisting of 25 `[0-9a-z]` characters and null.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ Scru128Generator

Function Documentation

◆ scru128_compare()

◆ scru128_copy()

◆ scru128_counter_hi()

◆ scru128_counter_lo()

◆ scru128_entropy()

◆ scru128_from_fields()

◆ scru128_from_str()

◆ scru128_generate()

◆ scru128_generate_or_abort_core()

◆ scru128_generate_or_reset_core()

◆ scru128_generate_string()

◆ scru128_timestamp()

◆ scru128_to_str()