Documentation
¶
Overview ¶
Package hlc implements a Hybrid Logical Clock (HLC) suitable for stamping mutations in Lantern's leaderless full-replica replication design.
The construction follows Kulkarni, Demirbas, Madappa, Avva and Leone, "Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases" (2014). An HLC timestamp interleaves a wall-clock component (nanoseconds since the Unix epoch) with a logical counter that bumps when two events would otherwise collide on the same wall instant. Comparison is lexicographic over (wallNs, logical, nodeID), giving a total order without requiring synchronized clocks while staying close to physical time.
This package is a leaf: it imports only the standard library. Wire encoding (proto round-trips) lives with the mutation message in pb/.
Index ¶
Constants ¶
const DefaultMaxSkew = 500 * time.Millisecond
DefaultMaxSkew is the default ceiling for the gap between a remote timestamp's wall component and local wall time. See replication RFC D3.
Variables ¶
var ErrSkewExceeded = errors.New("hlc: remote wall time exceeds MaxSkew")
ErrSkewExceeded is reported via [Clock.OnSkewExceeded] when an [Update] call observes a remote wall time more than MaxSkew ahead of local wall time. The remote timestamp is clamped, never rejected, so replication continues to make progress even when peers drift.
Functions ¶
This section is empty.
Types ¶
type Clock ¶
type Clock struct {
// contains filtered or unexported fields
}
Clock is a thread-safe Hybrid Logical Clock for a single origin node.
The zero value is not usable; construct with New.
func (*Clock) Now ¶
Now returns the next timestamp from this clock. The returned timestamp is strictly greater than every previously returned timestamp from the same clock and from any remote timestamp previously passed to Clock.Update.
func (*Clock) Update ¶
Update integrates a timestamp received from a peer. The returned timestamp is strictly greater than both the previous local state and remote, and the clock's internal state advances accordingly.
If remote.WallNs is more than the configured MaxSkew ahead of local wall time, the wall component is clamped to localWall + MaxSkew and the configured OnSkewExceeded callback fires with ErrSkewExceeded. The remote timestamp is never rejected — replication keeps making progress even when peers drift, and operators observe the drift through the callback (typically wired to a counter).
type NodeID ¶
type NodeID [16]byte
NodeID identifies the origin of a timestamp. It is opaque to this package; callers typically derive it from a stable per-process UUID.
type Options ¶
type Options struct {
// Now overrides the wall-time source. Useful for deterministic tests.
// Must return nanoseconds since the Unix epoch.
Now func() int64
// MaxSkew bounds how far ahead of local wall time a remote stamp may be
// before being clamped on Update. Zero means [DefaultMaxSkew].
MaxSkew time.Duration
// OnSkewExceeded is invoked, with the lock released, when Update clamps
// a remote timestamp. Use it to emit a metric or log line.
OnSkewExceeded func(remote Timestamp, localWallNs int64, err error)
}
Options configures a Clock. The zero value is valid: it uses the real monotonic wall clock, DefaultMaxSkew, and a no-op skew callback.
type Timestamp ¶
Timestamp is a Hybrid Logical Clock value.
WallNs holds nanoseconds since the Unix epoch as observed at the origin clock at the moment the timestamp was produced. Logical is a counter that distinguishes events that share a WallNs. NodeID breaks the remaining ties so that two distinct origins can never produce equal timestamps.
Source Files