macula_record_uuid (macula v11.1.0)

View Source

UUIDv7 (RFC 9562, section 5.7): random ids, and record versions that strictly increase on a node.

Bit layout (128 bits, 16 bytes):

   48b unix_ts_ms | 4b ver=7 | 12b rand_a | 2b var=10 | 62b rand_b
  

v7/0 fills rand_a and rand_b with random bits, for ids that need no order. v7_monotonic/1 is the version of a record this node signs (RFC 9562, section 6.2, method 1): rand_a is a counter within the millisecond, reseeded with a random 11-bit value at each new millisecond, and the 60 bits of millisecond and counter are the larger of that fresh prefix and the last one issued plus one. A counter that runs out moves to the next millisecond. So the versions a node issues strictly increase, also across a wall-clock step back.

A version is an order, not a time. A record's created_at stays the wall-clock fact; after a clock step back a version's millisecond field can run ahead of it, and nothing reads that field.

This process owns the table holding the last prefix issued and runs under macula_root. Callers advance it themselves, each version with at most three atomic table operations that only ever raise the row, so no version waits on a message or on another caller. Without the table, between an owner's exit and its restart, and after a restart, the next version starts again from the clock.

Summary

Functions

A random UUIDv7 at the wall clock, for an id that needs no order.

The next record version at wall-clock millisecond Ms: above every version this node issued before.

As v7_monotonic/1, from the table Table.

Types

options/0

-type options() :: #{table => atom()}.

Functions

handle_call(Request, From, Table)

handle_cast(Message, Table)

init(Options)

start_link()

-spec start_link() -> {ok, pid()} | {error, term()}.

start_link(Options)

-spec start_link(options()) -> {ok, pid()} | {error, term()}.

v7()

-spec v7() -> <<_:128>>.

A random UUIDv7 at the wall clock, for an id that needs no order.

v7_monotonic(Ms)

-spec v7_monotonic(non_neg_integer()) -> <<_:128>>.

The next record version at wall-clock millisecond Ms: above every version this node issued before.

v7_monotonic(Table, Ms)

-spec v7_monotonic(atom(), non_neg_integer()) -> <<_:128>>.

As v7_monotonic/1, from the table Table.