barrel_hlc (barrel_docdb v1.0.0)
View SourceHybrid Logical Clock utilities for barrel_docdb
HLC timestamps are used for ordering changes across distributed nodes. They combine physical wall clock time with a logical counter to ensure causality while maintaining a close relationship to real time.
Format: {WallTime, Logical} where WallTime is in milliseconds and Logical is a counter that increments when events happen in the physical clock's future.
Summary
Functions
Compare two timestamps. Returns lt if TS1 is before TS2, eq if equal, gt if TS1 is after TS2.
Decode binary to timestamp.
Encode timestamp to binary for storage. Uses big-endian encoding to maintain lexicographic sort order. Format: 12-byte binary with WallTime (64-bit) and Logical (32-bit).
Check if two timestamps are equal.
Alias for decode/1 for consistency with other modules.
Parse timestamp from string.
A timestamp at a given wall time (milliseconds since epoch) with a zero logical component. Used as a range cutoff (sorts before every real timestamp of that wall time).
Get the current global HLC timestamp without advancing the clock.
Check if TS1 is less than TS2.
Maximum timestamp value (for range scans).
Sync HLC from a base64-encoded HTTP header value. Silently ignores undefined or invalid values.
Minimum timestamp value (for range scans).
Generate a new global HLC timestamp, advancing the clock. Use this when generating a new event that needs to be ordered.
Generate a new timestamp for a local event using global clock.
Generate a new timestamp using a specific clock instance.
Start a new HLC clock with default settings. Uses physical system clock and no offset limit.
Start a new HLC clock with maximum offset limit. MaxOffset is the maximum allowed clock skew in milliseconds. A value of 0 disables offset checking.
Stop the HLC clock.
Synchronize with a remote HLC timestamp. Call this when receiving data from another node to maintain causality. Returns {ok, NewTimestamp} or {error, clock_skew}.
Get the current global timestamp without advancing the clock.
Get the current timestamp from a specific clock without advancing it.
Alias for encode/1 for consistency with other modules.
Convert timestamp to human-readable string. Format: "WallTime:Logical" (e.g., "1609459200000:42")
Update the global clock with a remote timestamp. Rejects non-timestamp input at the API boundary so a misuse cannot crash the global barrel_hlc_clock gen_server.
Update a specific clock with a remote timestamp.
Extract wall_time (milliseconds since epoch) from a timestamp.
Types
Functions
Compare two timestamps. Returns lt if TS1 is before TS2, eq if equal, gt if TS1 is after TS2.
Decode binary to timestamp.
Encode timestamp to binary for storage. Uses big-endian encoding to maintain lexicographic sort order. Format: 12-byte binary with WallTime (64-bit) and Logical (32-bit).
Check if two timestamps are equal.
Alias for decode/1 for consistency with other modules.
Parse timestamp from string.
-spec from_wall_time(non_neg_integer()) -> timestamp().
A timestamp at a given wall time (milliseconds since epoch) with a zero logical component. Used as a range cutoff (sorts before every real timestamp of that wall time).
-spec get_hlc() -> timestamp().
Get the current global HLC timestamp without advancing the clock.
Check if TS1 is less than TS2.
-spec max() -> timestamp().
Maximum timestamp value (for range scans).
-spec maybe_sync_from_header(binary() | undefined) -> ok.
Sync HLC from a base64-encoded HTTP header value. Silently ignores undefined or invalid values.
-spec min() -> timestamp().
Minimum timestamp value (for range scans).
-spec new_hlc() -> timestamp().
Generate a new global HLC timestamp, advancing the clock. Use this when generating a new event that needs to be ordered.
-spec now() -> timestamp().
Generate a new timestamp for a local event using global clock.
Generate a new timestamp using a specific clock instance.
-spec start_link() -> {ok, clock()}.
Start a new HLC clock with default settings. Uses physical system clock and no offset limit.
-spec start_link(MaxOffset :: non_neg_integer()) -> {ok, clock()}.
Start a new HLC clock with maximum offset limit. MaxOffset is the maximum allowed clock skew in milliseconds. A value of 0 disables offset checking.
Stop the HLC clock.
Synchronize with a remote HLC timestamp. Call this when receiving data from another node to maintain causality. Returns {ok, NewTimestamp} or {error, clock_skew}.
-spec timestamp() -> timestamp().
Get the current global timestamp without advancing the clock.
Get the current timestamp from a specific clock without advancing it.
Alias for encode/1 for consistency with other modules.
Convert timestamp to human-readable string. Format: "WallTime:Logical" (e.g., "1609459200000:42")
Update the global clock with a remote timestamp. Rejects non-timestamp input at the API boundary so a misuse cannot crash the global barrel_hlc_clock gen_server.
Update a specific clock with a remote timestamp.
-spec wall_time(timestamp()) -> non_neg_integer().
Extract wall_time (milliseconds since epoch) from a timestamp.