Documentation
¶
Overview ¶
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.
Index ¶
- func DurationFromNative(wire *Duration, native time.Duration) error
- func DurationToNative(wire Duration, native *time.Duration) error
- func TimeFromNative(wire *Time, native time.Time) error
- func TimeToNative(wire Time, native *time.Time) error
- func WireDeadlineFromNative(wire *WireDeadline, native Deadline) error
- func WireDeadlineToNative(wire WireDeadline, native *Deadline) error
- type Deadline
- type Duration
- type Time
- type WireDeadline
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DurationFromNative ¶
DurationFromNative is called by VDL for conversions from native to wire durations.
func DurationToNative ¶
DurationToNative is called by VDL for conversions from wire to native durations.
func TimeFromNative ¶
TimeFromNative is called by VDL for conversions from native to wire times.
func TimeToNative ¶
TimeToNative is called by VDL for conversions from wire to native times.
func WireDeadlineFromNative ¶
func WireDeadlineFromNative(wire *WireDeadline, native Deadline) error
WireDeadlineFromNative is called by VDL for conversions from native to wire deadlines.
func WireDeadlineToNative ¶
func WireDeadlineToNative(wire WireDeadline, native *Deadline) error
WireDeadlineToNative is called by VDL for conversions from wire to native deadlines.
Types ¶
type Deadline ¶
Deadline represents the deadline for an operation; it is the native representation for WireDeadline, and is automatically converted to/from WireDeadline during marshaling.
Deadline represents the deadline as an absolute time, while WireDeadline represents the deadline as a relative duration from "now".
To represent "no deadline", use the zero value for Deadline.
type Duration ¶
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
}
Duration represents the elapsed duration between two points in time, with up to nanosecond precision.
func (Duration) Normalize ¶
Normalize returns the normalized representation of x. It makes a best-effort attempt to clean up invalid values, e.g. if Nanos is outside the valid range, or the sign of Nanos doesn't match the sign of Seconds. The behavior is undefined for large invalid values, e.g. {int64max,int32max}.
func (Duration) VDLReflect ¶
type 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
func (Time) Normalize ¶
Normalize returns the normalized representation of x. It makes a best-effort attempt to clean up invalid values, e.g. if Nanos is outside the valid range, or the sign of Nanos doesn't match the sign of Seconds. The behavior is undefined for large invalid values, e.g. {int64max,int32max}.
func (Time) VDLReflect ¶
type WireDeadline ¶
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 time.Duration
}
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".
func (WireDeadline) VDLIsZero ¶
func (x WireDeadline) VDLIsZero() bool
func (WireDeadline) VDLReflect ¶
func (WireDeadline) VDLReflect(struct { Name string `vdl:"time.WireDeadline"` })
Source Files