| // 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". |
| FromNow Duration |
| // NoDeadline indicates there is no deadline; the analogous sentry for the |
| // native Deadline is the zero Time. |
| NoDeadline bool |
| } |