gnomon

README

Genomon

Genomon is the client library for accessing bounded time provided by clockd, clockd is not publicly available at this stage.

Genomon is the part of a sundial used for projecting a pinhole shadow image of the sun to tell the time of day.

Languages and platforms

Golang is natively supported, C support will be provided soon so C++, Python and Rust can be transparently supported.

Linux is support, with Darwin supported for development and testing purposes.

LICENSE

Genomon is the Apache2 licensed.

Documentation

Index

• Constants
• Variables
• func FirstError(err1 error, err2 error) error
• func GetClockUncertainty(nanosecond int64) uint64
• func UnmarshalClientInfo(data []byte, c *ClientInfo) error
• type Client
  • func NewClient(lockPath string, shmKey int) (*Client, error)
  • func (c *Client) Close() (err error)
  • func (c *Client) GetUnixTime() (UnixTime, error)
  • func (c *Client) WaitUntil(deadline UnixTime) error
• type ClientInfo
  • func (c *ClientInfo) Marshal(buf []byte) ([]byte, error)
• type Semaphore
  • func NewSemaphore(name string, mode, value uint32) (*Semaphore, error)
  • func (s *Semaphore) Close() error
  • func (s *Semaphore) Post() error
  • func (s *Semaphore) Unlink() error
  • func (s *Semaphore) Wait() error
• type UnixTime
  • func (t *UnixTime) Bounds() (uint64, uint64)
  • func (t *UnixTime) IsEmpty() bool
  • func (t *UnixTime) Sub(other UnixTime) int64

Constants

const (
	// Path of the lock file.
	DefaultLockPath string = "clockd.client.lock"
	// Key used for shared memory communication with clockd.
	DefaultShmKey int = 55356
	// buffer size of the shared memory.
	ClientInfoSharedMemoryBufferSize int = 48
)

const (
	// MaxClockDrift is the absolute value of the max clock drift in ppb. 1e3ppm
	// or 1e6ppb is picked based on Microsoft's FarmV2 survey, which found that
	// most oscillators would drift significantly less than 200ppm. This leaves
	// us a 5x error budget.
	//
	// Note that it is highly unlikely to see such a large drift on a working
	// clock as the underlying digital system require the drift to be bounded
	// at a much smaller range, e.g. Intel NIC typically require a 30ppm max
	// drift for its SerDes and a 300ppm max drift for PCI-E, see Intel 82599
	// datasheet for more details. On the software side, kernel accepts 500ppm
	// maximum adjustment, meaning anything higher than that reflects a hardware
	// fault.
	MaxClockDrift int64 = 1000000
)

Variables

var (
	// ErrNotReady indicates that clockd is not ready yet.
	ErrNotReady = errors.New("bounded time service not ready")
	// ErrStopped indicates that clockd unexpectedly stopped, e.g. crashed.
	ErrStopped = errors.New("bounded time service stopped")
)

var (
	// Encoder used for content stored in the shared memory region.
	Encoder = binary.BigEndian
)

Functions

func FirstError

func FirstError(err1 error, err2 error) error

func GetClockUncertainty

func GetClockUncertainty(nanosecond int64) uint64

GetClockUncertainty returns the dispersion introduced by the clock itself when we can not confirm whether it is broken or not. When there is a nanosecond worth of uncertain period, we multiply it with the MaxClockDrift to get the dispersion.

func UnmarshalClientInfo

func UnmarshalClientInfo(data []byte, c *ClientInfo) error

Types

type Client

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

Client is the client used to get current bounded time. It is not thread safe meaning you shouldn't be using the same client concurrently from multiple threads.

func NewClient

func NewClient(lockPath string, shmKey int) (*Client, error)

NewClient creates a new Client instance.

func (*Client) Close

func (c *Client) Close() (err error)

Close closes the client instance.

func (*Client) GetUnixTime

func (c *Client) GetUnixTime() (UnixTime, error)

GetUnixTime returns the UnixTime instance that represents the current time with reported uncertainty.

func (*Client) WaitUntil

func (c *Client) WaitUntil(deadline UnixTime) error

WaitUntil does not return until the sys clock time is later than the specified deadline with all uncertainties considered. That is, WaitUntil() will not return until the sys clock time is definiately past the specified deadline.

type ClientInfo

type ClientInfo struct {
	Valid      bool
	Locked     bool
	Count      uint16
	Dispersion uint64
	Sec        uint64
	NSec       uint32
}

ClientInfo contains details exposed by clockd. Applications shouldn't be accessing any fields. All fields are in Unix time.

func (*ClientInfo) Marshal

func (c *ClientInfo) Marshal(buf []byte) ([]byte, error)

type Semaphore

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

func NewSemaphore

func NewSemaphore(name string, mode, value uint32) (*Semaphore, error)

Open creates a new POSIX semaphore or opens an existing semaphore. The semaphore is identified by name. The mode argument specifies the permissions to be placed on the new semaphore. The value argument specifies the initial value for the new semaphore. If the named semaphore already exist, mode and value are ignored. For details see sem_overview(7).

func (*Semaphore) Close

func (s *Semaphore) Close() error

Close closes the named semaphore, allowing any resources that the system has allocated to the calling process for this semaphore to be freed.

func (*Semaphore) Post

func (s *Semaphore) Post() error

Post increments the semaphore.

func (*Semaphore) Unlink

func (s *Semaphore) Unlink() error

Unlink removes the named semaphore. The semaphore name is removed immediately. The semaphore is destroyed once all other processes that have the semaphore open close it.

func (*Semaphore) Wait

func (s *Semaphore) Wait() error

Wait decrements the semaphore. If the semaphore's value is greater than zero, then the decrement proceeds, and the function returns, immediately. If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement, or a signal interrupts the call.

type UnixTime

type UnixTime struct {
	Sec        uint64
	NSec       uint32
	Dispersion uint64
}

UnixTime is the native time provided by clockd. It is used to represent current and future time with specified time uncertainties. Use time types from the stdlib or other 3rd libraries for generic time values. The Dispersion member is the uncertainty of the specified time meaning that for time t, the actual time is between [t-Dispersion, t+Dispersion] both inclusive.

func (*UnixTime) Bounds

func (t *UnixTime) Bounds() (uint64, uint64)

Bounds returns the lower and upper limit of the time represented by the UnixTime instance.

func (*UnixTime) IsEmpty

func (t *UnixTime) IsEmpty() bool

IsEmpty returns a boolean flag indicating whether the UnixTime instance is an empty value.

func (*UnixTime) Sub

func (t *UnixTime) Sub(other UnixTime) int64

Sub returns the time difference of (t - other) in nanoseconds.