diff --git a/README.md b/README.md index 49b40b9..e1018be 100644 --- a/README.md +++ b/README.md @@ -66,20 +66,21 @@ default-monotonic-clock: monotonic-clock ``` ```rust - let start: Instant = monotonic_clock::now(clock); + let start: MonotonicClockPoint = monotonic_clock::now(clock); // some stuff - let stop: Instant = monotonic_clock::now(clock); + let stop: MonotonicClockPoint = monotonic_clock::now(clock); - let elapsed: Instant = stop - start; + let elapsed: MonotonicClockPoint = stop - start; + // NOTE: should be `elapsed: Duration`? ``` #### Telling the current human time: ```rust - let the_current_time = wall_clock::now(); + let the_current_time = system_clock::now(); println!("it has been {} seconds and {} nanoseconds since the Unix epoch!", the_current_time.seconds, the_current_time.nanoseconds); ``` @@ -87,11 +88,10 @@ default-monotonic-clock: monotonic-clock #### Retrieving the timezone: ```rust - let datetime: Datetime = wall_clock::now(); - - let timezone_display: TimezoneDisplay = timezone::display(datetime); - - println!("the timezone is {}", timezone_display.name); + let instant: Instant = system_clock::now(); + let id = timezone::id(); + let offset_h = timezone::utc_offset(instant) as f64 / 3600e9; + println!("the timezone is {} at UTC{:+}", id, offset_h); ``` ### Detailed design discussion @@ -100,14 +100,14 @@ default-monotonic-clock: monotonic-clock In POSIX, `clock_gettime` uses a single `timespec` type to represent timestamps from all clocks, with two fields: seconds and nanoseconds. However, in applications -that just need to measure elapsed time, and don't need to care about wall clock +that just need to measure elapsed time, and don't need to care about absolute time, working with seconds and nanoseconds as separate fields adds extra code size and complexity. For these use cases, a single 64-bit nanoseconds value, which can measure up to about 584 years, is sufficient and simpler. -For wall clock time, it's still useful to have both seconds and nanoseconds, both +For system time, it's still useful to have both seconds and nanoseconds, both to be able to represent dates in the far future, and to reflect the fact that -code working with wall clock time will often want to treat seconds and fractions +code working with system time will often want to treat seconds and fractions of seconds differently. And so, this API uses different data types for different types of clocks. diff --git a/imports.md b/imports.md index 8b977ac..a96f702 100644 --- a/imports.md +++ b/imports.md @@ -4,7 +4,7 @@ @@ -71,9 +71,9 @@ successive reads of the clock will produce non-decreasing values.

type pollable

pollable

-#### `type instant` +#### `type monotonic-clock-point` `u64` -

An instant in time, in nanoseconds. An instant is relative to an +

A monotonic clock point in nanoseconds. A clock point is relative to an unspecified initial value, and can only be compared to instances from the same monotonic-clock.

type duration

@@ -87,7 +87,7 @@ the same monotonic-clock. produce a sequence of non-decreasing values.

Return values

resolution: func

Query the resolution of the clock. Returns the duration of time @@ -96,16 +96,16 @@ corresponding to a clock tick.

-

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant +

subscribe-clock-point: func

+

Create a pollable which will resolve once the specified clock point has occured.

Params
Return values

subscribe-duration: func

Create a pollable that will resolve after the specified duration has @@ -118,25 +118,25 @@ elapsed from the time this function is invoked.

-

Import interface wasi:clocks/wall-clock@0.2.0

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

+

Import interface wasi:clocks/system-clock@0.2.0

+

WASI System Clock is a clock API intended to let users query the current +time. The clock is not necessarily monotonic as it may be reset.

It is intended to be portable at least between Unix-family platforms and Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

+

An "instant", or "exact time", is a point in time without regard to any time +zone: just the time since a particular external reference point, often +called an "epoch".

External references may be reset, so this clock is not necessarily monotonic, making it unsuitable for measuring elapsed time.

It is intended for reporting the current date and time for humans.

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

+

record instant

+

An exact time in seconds plus nanoseconds.

Record Fields

Functions

@@ -150,77 +150,51 @@ also known as Unix Time.The nanoseconds field of the output is always less than 1000000000.

Return values

resolution: func

Query the resolution of the clock.

The nanoseconds field of the output is always less than 1000000000.

Return values

Import interface wasi:clocks/timezone@0.2.0

Types

-

type datetime

-

datetime

+

type instant

+

instant

-#### `record timezone-display` -

Information useful for displaying the timezone of a specific datetime.

-

This information may vary within a single timezone to reflect daylight -saving time adjustments.

-
Record Fields
- -
-

Functions

-

display: func

-

Return information needed to display the given datetime. This includes -the UTC offset, the time zone name, and a flag indicating whether -daylight saving time is active.

-

If the timezone cannot be determined for the given datetime, return a -timezone-display for UTC with a utc-offset of 0 and no daylight -saving time.

-
Params
-
Return values

utc-offset: func

-

The same as display, but only return the UTC offset.

+

The number of nanoseconds difference between UTC time and the local +time of the currently configured timezone at the exact time of +instant.

+

The magnitude of the returned value will always be less than +86,400,000,000,000 which is the number of nanoseconds in a day +(246060*1e9).

+

In implementations that do not expose an actual time zone, this +should return 0.

Params
Return values
diff --git a/wit/monotonic-clock.wit b/wit/monotonic-clock.wit index cae2363..5e5b71f 100644 --- a/wit/monotonic-clock.wit +++ b/wit/monotonic-clock.wit @@ -12,11 +12,11 @@ interface monotonic-clock { @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; - /// An instant in time, in nanoseconds. An instant is relative to an + /// A monotonic clock point in nanoseconds. A clock point is relative to an /// unspecified initial value, and can only be compared to instances from /// the same monotonic-clock. @since(version = 0.2.0) - type instant = u64; + type monotonic-clock-point = u64; /// A duration of time, in nanoseconds. @since(version = 0.2.0) @@ -27,18 +27,18 @@ interface monotonic-clock { /// The clock is monotonic, therefore calling this function repeatedly will /// produce a sequence of non-decreasing values. @since(version = 0.2.0) - now: func() -> instant; + now: func() -> monotonic-clock-point; /// Query the resolution of the clock. Returns the duration of time /// corresponding to a clock tick. @since(version = 0.2.0) resolution: func() -> duration; - /// Create a `pollable` which will resolve once the specified instant + /// Create a `pollable` which will resolve once the specified clock point /// has occured. @since(version = 0.2.0) - subscribe-instant: func( - when: instant, + subscribe-clock-point: func( + when: monotonic-clock-point, ) -> pollable; /// Create a `pollable` that will resolve after the specified duration has diff --git a/wit/wall-clock.wit b/wit/system-clock.wit similarity index 65% rename from wit/wall-clock.wit rename to wit/system-clock.wit index 4b08d71..af65533 100644 --- a/wit/wall-clock.wit +++ b/wit/system-clock.wit @@ -1,23 +1,23 @@ package wasi:clocks@0.2.0; -/// WASI Wall Clock is a clock API intended to let users query the current -/// time. The name "wall" makes an analogy to a "clock on the wall", which -/// is not necessarily monotonic as it may be reset. +/// WASI System Clock is a clock API intended to let users query the current +/// time. The clock is not necessarily monotonic as it may be reset. /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. /// -/// A wall clock is a clock which measures the date and time according to -/// some external reference. +/// An "instant", or "exact time", is a point in time without regard to any time +/// zone: just the time since a particular external reference point, often +/// called an "epoch". /// /// External references may be reset, so this clock is not necessarily /// monotonic, making it unsuitable for measuring elapsed time. /// /// It is intended for reporting the current date and time for humans. @since(version = 0.2.0) -interface wall-clock { - /// A time and date in seconds plus nanoseconds. +interface system-clock { + /// An exact time in seconds plus nanoseconds. @since(version = 0.2.0) - record datetime { + record instant { seconds: u64, nanoseconds: u32, } @@ -36,11 +36,14 @@ interface wall-clock { /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time @since(version = 0.2.0) - now: func() -> datetime; + now: func() -> instant; /// Query the resolution of the clock. /// /// The nanoseconds field of the output is always less than 1000000000. @since(version = 0.2.0) - resolution: func() -> datetime; + resolution: func() -> instant; + // NOTE: This return value doesn't represent an exact time, so maybe is not + // a correct use of the Instant type. Would it make sense to have a + // system-clock::duration analogous to monotonic-clock::duration? } diff --git a/wit/timezone.wit b/wit/timezone.wit index 3c28688..be59640 100644 --- a/wit/timezone.wit +++ b/wit/timezone.wit @@ -3,53 +3,33 @@ package wasi:clocks@0.2.0; @unstable(feature = clocks-timezone) interface timezone { @unstable(feature = clocks-timezone) - use wall-clock.{datetime}; + use system-clock.{instant}; - /// Return information needed to display the given `datetime`. This includes - /// the UTC offset, the time zone name, and a flag indicating whether - /// daylight saving time is active. + /// Return the IANA identifier of the currently configured timezone. The id + /// `UTC` indicates Coordinated Universal Time. Otherwise, this should be an + /// identifier from the IANA Time Zone Database. /// - /// If the timezone cannot be determined for the given `datetime`, return a - /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight - /// saving time. - @unstable(feature = clocks-timezone) - display: func(when: datetime) -> timezone-display; - - /// The same as `display`, but only return the UTC offset. + /// For displaying to a user, the identifier should be converted into a + /// localized name by means of an internationalization API. + /// + /// In implementations that do not expose an actual time zone, this + /// should be the string `UTC`. + /// + /// In time zones that do not have an applicable name, a formatted + /// representation of the UTC offset may be returned, such as `-04:00`. @unstable(feature = clocks-timezone) - utc-offset: func(when: datetime) -> s32; + id: func() -> string; - /// Information useful for displaying the timezone of a specific `datetime`. + /// The number of nanoseconds difference between UTC time and the local + /// time of the currently configured timezone at the exact time of + /// `instant`. /// - /// This information may vary within a single `timezone` to reflect daylight - /// saving time adjustments. + /// The magnitude of the returned value will always be less than + /// 86,400,000,000,000 which is the number of nanoseconds in a day + /// (24*60*60*1e9). + /// + /// In implementations that do not expose an actual time zone, this + /// should return 0. @unstable(feature = clocks-timezone) - record timezone-display { - /// The number of seconds difference between UTC time and the local - /// time of the timezone. - /// - /// The returned value will always be less than 86400 which is the - /// number of seconds in a day (24*60*60). - /// - /// In implementations that do not expose an actual time zone, this - /// should return 0. - utc-offset: s32, - - /// The abbreviated name of the timezone to display to a user. The name - /// `UTC` indicates Coordinated Universal Time. Otherwise, this should - /// reference local standards for the name of the time zone. - /// - /// In implementations that do not expose an actual time zone, this - /// should be the string `UTC`. - /// - /// In time zones that do not have an applicable name, a formatted - /// representation of the UTC offset may be returned, such as `-04:00`. - name: string, - - /// Whether daylight saving time is active. - /// - /// In implementations that do not expose an actual time zone, this - /// should return false. - in-daylight-saving-time: bool, - } + utc-offset: func(when: instant) -> s64; } diff --git a/wit/world.wit b/wit/world.wit index 76a9206..a27918e 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -5,7 +5,7 @@ world imports { @since(version = 0.2.0) import monotonic-clock; @since(version = 0.2.0) - import wall-clock; + import system-clock; @unstable(feature = clocks-timezone) import timezone; }