hlc

package
v0.0.0-...-ad86efc Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2016 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package hlc implements the Hybrid Logical Clock outlined in "Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases", available online at http://www.cse.buffalo.edu/tech-reports/2014-04.pdf.

Package hlc is a generated protocol buffer package.

It is generated from these files:
	cockroach/util/hlc/timestamp.proto

It has these top-level messages:
	Timestamp

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// MaxTimestamp is the max value allowed for Timestamp.
	MaxTimestamp = Timestamp{WallTime: math.MaxInt64, Logical: math.MaxInt32}
	// MinTimestamp is the min value allowed for Timestamp.
	MinTimestamp = Timestamp{WallTime: 0, Logical: 1}
	// ZeroTimestamp is an empty timestamp.
	ZeroTimestamp = Timestamp{WallTime: 0, Logical: 0}
)

Timestamp constant values.

View Source
var (
	ErrInvalidLengthTimestamp = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowTimestamp   = fmt.Errorf("proto: integer overflow")
)

Functions

func UnixNano

func UnixNano() int64

UnixNano returns the local machine's physical nanosecond unix epoch timestamp as a convenience to create a HLC via c := hlc.NewClock(hlc.UnixNano).

Types

type Clock

type Clock struct {

	// Clock contains a mutex used to lock the below
	// fields while methods operate on them.
	syncutil.Mutex
	// contains filtered or unexported fields
}

Clock is a hybrid logical clock. Objects of this type model causality while maintaining a relation to physical time. Roughly speaking, timestamps consist of the largest wall clock time among all events, and a logical clock that ticks whenever an event happens in the future of the local physical clock. The data structure is thread safe and thus can safely be shared by multiple goroutines.

See NewClock for details.

func NewClock

func NewClock(physicalClock func() int64) *Clock

NewClock creates a new hybrid logical clock associated with the given physical clock, initializing both wall time and logical time with zero.

The physical clock is typically given by the wall time of the local machine in unix epoch nanoseconds, using hlc.UnixNano. This is not a requirement.

Example

ExampleNewClock shows how to create a new hybrid logical clock based on the local machine's physical clock. The sanity checks in this example will, of course, not fail and the output will be the age of the Unix epoch in nanoseconds.

// Initialize a new clock, using the local
// physical clock.
c := NewClock(UnixNano)
// Update the state of the hybrid clock.
s := c.Now()
time.Sleep(50 * time.Nanosecond)
t := Timestamp{WallTime: UnixNano()}
// The sanity checks below will usually never be triggered.

if s.Less(t) || !t.Less(s) {
	log.Fatalf(context.Background(), "The later timestamp is smaller than the earlier one")
}

if t.WallTime-s.WallTime > 0 {
	log.Fatalf(context.Background(), "HLC timestamp %d deviates from physical clock %d", s, t)
}

if s.Logical > 0 {
	log.Fatalf(context.Background(), "Trivial timestamp has logical component")
}

fmt.Printf("The Unix Epoch is now approximately %dns old.\n", t.WallTime)
Output:

func (*Clock) MaxOffset

func (c *Clock) MaxOffset() time.Duration

MaxOffset returns the maximal offset allowed. A value of 0 means offset checking is disabled. See SetMaxOffset for details.

func (*Clock) Now

func (c *Clock) Now() Timestamp

Now returns a timestamp associated with an event from the local machine that may be sent to other members of the distributed network. This is the counterpart of Update, which is passed a timestamp received from another member of the distributed network.

func (*Clock) PhysicalNow

func (c *Clock) PhysicalNow() int64

PhysicalNow returns the local wall time. It corresponds to the physicalClock provided at instantiation. For a timestamp value, use Now() instead.

func (*Clock) PhysicalTime

func (c *Clock) PhysicalTime() time.Time

PhysicalTime returns a time.Time struct using the local wall time.

func (*Clock) SetMaxOffset

func (c *Clock) SetMaxOffset(delta time.Duration)

SetMaxOffset sets the maximal offset of the physical clock from the cluster. It is used to set the max offset a call to Update may cause and to ensure an upperbound on timestamp WallTime in transactions. A well-chosen value is large enough to ignore a reasonable amount of clock skew but will prevent ill-configured nodes from dramatically skewing the wall time of the clock into the future.

A value of zero disables all safety features. The default value for a new instance is zero.

func (*Clock) Timestamp

func (c *Clock) Timestamp() Timestamp

Timestamp returns a copy of the clock's current timestamp, without performing a clock adjustment.

func (*Clock) Update

func (c *Clock) Update(rt Timestamp) Timestamp

Update takes a hybrid timestamp, usually originating from an event received from another member of a distributed system. The clock is updated and the hybrid timestamp associated to the receipt of the event returned. An error may only occur if offset checking is active and the remote timestamp was rejected due to clock offset, in which case the state of the clock will not have been altered. To timestamp events of local origin, use Now instead.

type ManualClock

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

ManualClock is a convenience type to facilitate creating a hybrid logical clock whose physical clock is manually controlled. ManualClock is thread safe.

func NewManualClock

func NewManualClock(nanos int64) *ManualClock

NewManualClock returns a new instance, initialized with specified timestamp.

func (*ManualClock) Increment

func (m *ManualClock) Increment(incr int64)

Increment atomically increments the manual clock's timestamp.

func (*ManualClock) Set

func (m *ManualClock) Set(nanos int64)

Set atomically sets the manual clock's timestamp.

func (*ManualClock) UnixNano

func (m *ManualClock) UnixNano() int64

UnixNano returns the underlying manual clock's timestamp.

type Timestamp

type Timestamp struct {
	// Holds a wall time, typically a unix epoch time
	// expressed in nanoseconds.
	WallTime int64 `protobuf:"varint,1,opt,name=wall_time,json=wallTime" json:"wall_time"`
	// The logical component captures causality for events whose wall
	// times are equal. It is effectively bounded by (maximum clock
	// skew)/(minimal ns between events) and nearly impossible to
	// overflow.
	Logical int32 `protobuf:"varint,2,opt,name=logical" json:"logical"`
}

Timestamp represents a state of the hybrid logical clock.

func NewPopulatedTimestamp

func NewPopulatedTimestamp(r randyTimestamp, easy bool) *Timestamp

func (Timestamp) Add

func (t Timestamp) Add(wallTime int64, logical int32) Timestamp

Add returns a timestamp with the WallTime and Logical components increased. wallTime is expressed in nanos.

func (*Timestamp) Backward

func (t *Timestamp) Backward(s Timestamp)

Backward updates the timestamp from the one given, if that moves it backwards in time.

func (*Timestamp) Descriptor

func (*Timestamp) Descriptor() ([]byte, []int)

func (Timestamp) Equal

func (t Timestamp) Equal(s Timestamp) bool

Equal returns whether two timestamps are the same.

func (*Timestamp) Forward

func (t *Timestamp) Forward(s Timestamp)

Forward updates the timestamp from the one given, if that moves it forwards in time.

func (Timestamp) GoTime

func (t Timestamp) GoTime() time.Time

GoTime converts the timestamp to a time.Time.

func (Timestamp) Less

func (t Timestamp) Less(s Timestamp) bool

Less compares two timestamps.

func (*Timestamp) Marshal

func (m *Timestamp) Marshal() (data []byte, err error)

func (*Timestamp) MarshalTo

func (m *Timestamp) MarshalTo(data []byte) (int, error)

func (Timestamp) Next

func (t Timestamp) Next() Timestamp

Next returns the timestamp with the next later timestamp.

func (Timestamp) Prev

func (t Timestamp) Prev() Timestamp

Prev returns the next earliest timestamp.

func (*Timestamp) ProtoMessage

func (*Timestamp) ProtoMessage()

func (*Timestamp) Reset

func (m *Timestamp) Reset()

func (*Timestamp) Size

func (m *Timestamp) Size() (n int)

func (Timestamp) String

func (t Timestamp) String() string

func (*Timestamp) Unmarshal

func (m *Timestamp) Unmarshal(data []byte) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL