vdlroot/time/time.vdl

// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package time defines standard representations of absolute and relative times.
//
// The representations described below are required to provide wire
// compatibility between different programming environments.  Generated code for
// different environments typically provide automatic conversions into native
// representations, for simpler idiomatic usage.
package time

// Representing dates and times is a complicated topic.  Some of the issues:
// 1) The earth's rate of rotation is not regular.
//    http://en.wikipedia.org/wiki/Leap_second
//    http://en.wikipedia.org/wiki/Coordinated_Universal_Time
//    http://en.wikipedia.org/wiki/International_Atomic_Time
// 2) There are different standards for defining calendars.
//    http://en.wikipedia.org/wiki/0_(year)
//    http://en.wikipedia.org/wiki/Julian_calendar
//    http://en.wikipedia.org/wiki/Gregorian_calendar
//    http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
//
// The most important choice is whether to represent time as a count of ticks
// since an epoch (tick time), or as a date/time for a particular calendar
// (calendar time).  Tick time maps naturally to hardware clocks, is cheap to
// represent, and allows using simple subtraction for computing durations.
// Calendar time is typically more semantically meaningful.  Conversions between
// tick time and calendar time are complicated by the above issues.
//
// http://en.wikipedia.org/wiki/ISO_8601
// http://en.wikipedia.org/wiki/System_time

// Time represents an absolute point in time with up to nanosecond precision.
//
// Time is represented as the duration before or after a fixed epoch.  The zero
// Time represents the epoch 0001-01-01T00:00:00.000000000Z.  This uses the
// proleptic Gregorian calendar; the calendar runs on an exact 400 year cycle.
// Leap seconds are "smeared", ensuring that no leap second table is necessary
// for interpretation.
//
// This is similar to Go time.Time, but always in the UTC location.
// http://golang.org/pkg/time/#Time
//
// This is similar to conventional "unix time", but with the epoch defined at
// year 1 rather than year 1970.  This allows the zero Time to be used as a
// natural sentry, since it isn't a valid time for many practical applications.
// http://en.wikipedia.org/wiki/Unix_time
type Time Duration

// Duration represents the elapsed duration between two points in time, with
// up to nanosecond precision.
type Duration struct {
	// Seconds represents the seconds in the duration.  The range is roughly
	// +/-290 billion years, larger than the estimated age of the universe.
	Seconds int64
	// Nanos represents the fractions of a second at nanosecond resolution.  Must
	// be in the inclusive range between +/-999,999,999.
	//
	// In normalized form, durations less than one second are represented with 0
	// Seconds and +/-Nanos.  For durations one second or more, the sign of Nanos
	// must match Seconds, or be 0.
	Nanos int32
}

// WireDeadline represents the deadline for an operation, where the operation is
// expected to finish before the deadline.  The intended usage is for a client
// to set a deadline on an operation, say one minute from "now", and send the
// deadline to a server.  The server is expected to finish the operation before
// the deadline.
//
// On a single device, it is simplest to represent a deadline as an absolute
// time; when the time now reaches the deadline, the deadline has expired.
// However when sending a deadline between devices with potential clock skew, it
// is often more robust to represent the deadline as a duration from "now".  The
// sender computes the duration from its notion of "now", while the receiver
// computes the absolute deadline from its own notion of "now".
//
// This representation doesn't account for propagation delay, but does ensure
// that the deadline used by the receiver is no earlier than the deadline
// intended by the client.  In many common scenarios the propagation delay is
// small compared to the potential clock skew, making this a simple but
// effective approach.
//
// WireDeadline typically has a native representation called Deadline that is an
// absolute Time, which automatically performs the sender and receiver
// conversions from "now".
type WireDeadline struct {
	// FromNow represents the deadline as a duration from "now".  As a
	// special-case, the 0 duration indicates that there is no deadline; i.e. the
	// deadline is "infinite".
	FromNow Duration
}