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

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

Author: bakkot

README.md

@@ -71,30 +71,30 @@ default-monotonic-clock: monotonic-clock
 ```
 
 ```rust
-   let start: Instant = monotonic_clock::now(clock);
+   let start: Mark = monotonic_clock::now(clock);
 
    // some stuff
 
-   let stop: Instant = monotonic_clock::now(clock);
+   let stop: Mark = monotonic_clock::now(clock);
 
-   let elapsed: Instant = stop - start;
+   let elapsed: Duration = stop - start;
 ```
 
 
 #### 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 +105,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,11 +9,11 @@ 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 mark on a monotonic clock is a number of nanoseconds since an
     /// unspecified initial value, and can only be compared to instances from
     /// the same monotonic-clock.
     @since(version = 0.3.0)
-    type instant = u64;
+    type mark = u64;
 
     /// A duration of time, in nanoseconds.
     @since(version = 0.3.0)
@@ -24,20 +24,20 @@ 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() -> mark;
 
     /// Query the resolution of the clock. Returns the duration of time
     /// corresponding to a clock tick.
     @since(version = 0.3.0)
     get-resolution: func() -> duration;
 
-    /// Wait until the specified instant has occurred.
+    /// Wait until the specified mark has occurred.
     @since(version = 0.3.0)
     wait-until: async func(
-        when: instant,
+        when: mark,
     );
 
-    /// Wait for the specified duration has elapsed.
+    /// Wait for the specified duration.
     @since(version = 0.3.0)
     wait-for: async func(
         how-long: duration,

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

@@ -1,27 +1,38 @@
 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.
-///
 /// 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 "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".
+    /// Note that even if the seconds field is negative, incrementing
+    /// nanoseconds always represents moving forwards in time.
+    /// For example, `{ -1 seconds, 999999999 nanoseconds }` represents the
+    /// instant one nanosecond before the epoch.
+    /// For more on various different ways to represent time, see
+    /// https://tc39.es/proposal-temporal/docs/timezone.html
     @since(version = 0.3.0)
-    record datetime {
-        seconds: u64,
+    record instant {
+        seconds: s64,
         nanoseconds: u32,
     }
 
+    /// A duration of time, in seconds plus nanoseconds.
+    @since(version = 0.3.0)
+    type duration = {
+        seconds: u64,
+        nanoseconds: u32,
+    };
+
     /// Read the current value of the clock.
     ///
     /// This clock is not monotonic, therefore calling this function repeatedly
@@ -36,11 +47,11 @@ 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)
-    get-resolution: func() -> datetime;
+    get-resolution: func() -> 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;
 }