Avoid nonstandard use of names for types in wit-0.3.0-draft

Co-authored-by: Philip Chimento <[email protected]>

Author: bakkot

README.md

@@ -78,23 +78,24 @@ default-monotonic-clock: monotonic-clock
    let stop: Instant = monotonic_clock::now(clock);
 
    let elapsed: Instant = 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);
 ```
 
 #### Retrieving the timezone:
 
 ```rust
-    let datetime: Datetime = wall_clock::now();
+    let instant: Instant = system_clock::now();
 
-    let timezone_display: TimezoneDisplay = timezone::display(datetime);
+    let timezone_display: TimezoneDisplay = timezone::display(instant);
 
     println!("the timezone is {}", timezone_display.name);
 ```
@@ -105,14 +106,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.

wit-0.3.0-draft/monotonic-clock.wit

@@ -9,7 +9,7 @@ package wasi:[email protected];
 /// successive reads of the clock will produce non-decreasing values.
 @since(version = 0.3.0)
 interface monotonic-clock {
-    /// 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.3.0)
@@ -24,17 +24,17 @@ interface monotonic-clock {
     /// The clock is monotonic, therefore calling this function repeatedly will
     /// produce a sequence of non-decreasing values.
     @since(version = 0.3.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.3.0)
     resolution: func() -> duration;
 
-    /// Wait until the specified instant has occurred.
+    /// Wait until the specified clock point has occurred.
     @since(version = 0.3.0)
     wait-until: func(
-        when: instant,
+        when: monotonic-clock-point,
     );
 
     /// Wait for the specified duration has elapsed.

wit-0.3.0-draft/wall-clock.wit renamed to wit-0.3.0-draft/system-clock.wit

@@ -1,23 +1,23 @@
 package wasi:clocks@0.3.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.3.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.3.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.3.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.3.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?
 }

wit-0.3.0-draft/timezone.wit

@@ -3,23 +3,23 @@ package wasi:[email protected];
 @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
+    /// Return information needed to display the given `instant`. 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
+    /// If the timezone cannot be determined for the given `instant`, 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;
+    display: func(when: instant) -> timezone-display;
 
     /// The same as `display`, but only return the UTC offset.
     @unstable(feature = clocks-timezone)
-    utc-offset: func(when: datetime) -> s32;
+    utc-offset: func(when: instant) -> s32;
 
-    /// Information useful for displaying the timezone of a specific `datetime`.
+    /// Information useful for displaying the timezone of a specific `instant`.
     ///
     /// This information may vary within a single `timezone` to reflect daylight
     /// saving time adjustments.

wit-0.3.0-draft/world.wit

@@ -5,7 +5,7 @@ world imports {
     @since(version = 0.3.0)
     import monotonic-clock;
     @since(version = 0.3.0)
-    import wall-clock;
+    import system-clock;
     @unstable(feature = clocks-timezone)
     import timezone;
 }