hlc

Documentation

Overview

Package hlc is a Hybrid Logical Clock: physical wall-clock milliseconds plus a logical counter. It orders events consistently across instances even when they are offline, reconnect at different times, or have clock skew - which a plain per-record version cannot do. Last-writer-wins conflict resolution compares (Wall, Counter) then breaks ties by writer id.

The physical clock is injectable, so a replay reproduces the same timestamps deterministically; the default is the system clock.

Index

• type Clock
  • func NewClock(opts ...Option) *Clock
  • func (c *Clock) Now() Time
  • func (c *Clock) Observe(remote Time) Time
• type Option
  • func WithPhysical(c clock.Clock) Option
• type Time
  • func (t Time) Before(u Time) bool
  • func (t Time) Compare(u Time) int
  • func (t Time) IsZero() bool
  • func (t Time) String() string

Types

type Clock

type Clock struct {
	// contains filtered or unexported fields
}

Clock issues monotonic HLC timestamps from an injectable physical clock. It is safe for concurrent use.

func NewClock

func NewClock(opts ...Option) *Clock

NewClock returns a Clock defaulting to the system physical clock.

func (*Clock) Now

func (c *Clock) Now() Time

Now returns the next timestamp, strictly after every prior Now and Observe.

func (*Clock) Observe

func (c *Clock) Observe(remote Time) Time

Observe advances the clock past a timestamp received from another instance (during sync), preserving causality, and returns the new local time.

type Option

type Option func(*Clock)

Option configures a Clock.

func WithPhysical

func WithPhysical(c clock.Clock) Option

WithPhysical sets the physical clock (default: clock.System).

type Time

type Time struct {
	Wall    int64  // unix milliseconds
	Counter uint16 // logical counter, disambiguating events within the same Wall
}

Time is an HLC timestamp. It is comparable by Wall then Counter; the zero value precedes every real timestamp.

func (Time) Before

func (t Time) Before(u Time) bool

Before reports whether t happened before u.

func (Time) Compare

func (t Time) Compare(u Time) int

Compare returns -1, 0, or 1 as t is before, equal to, or after u.

func (Time) IsZero

func (t Time) IsZero() bool

IsZero reports whether t is the zero timestamp.

func (Time) String

func (t Time) String() string

String renders the timestamp as "wall.counter".