1package wasi:[email protected];
2
3/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
4/// time.
5///
6/// It is intended to be portable at least between Unix-family platforms and
7/// Windows.
8///
9/// A monotonic clock is a clock which has an unspecified initial value, and
10/// successive reads of the clock will produce non-decreasing values.
11@since(version = 0.2.0)
12interface monotonic-clock {
13  @since(version = 0.2.0)
14  use wasi:io/poll@0.2.6.{pollable};
15
16  /// An instant in time, in nanoseconds. An instant is relative to an
17  /// unspecified initial value, and can only be compared to instances from
18  /// the same monotonic-clock.
19  @since(version = 0.2.0)
20  type instant = u64;
21
22  /// A duration of time, in nanoseconds.
23  @since(version = 0.2.0)
24  type duration = u64;
25
26  /// Read the current value of the clock.
27  ///
28  /// The clock is monotonic, therefore calling this function repeatedly will
29  /// produce a sequence of non-decreasing values.
30  @since(version = 0.2.0)
31  now: func() -> instant;
32
33  /// Query the resolution of the clock. Returns the duration of time
34  /// corresponding to a clock tick.
35  @since(version = 0.2.0)
36  resolution: func() -> duration;
37
38  /// Create a `pollable` which will resolve once the specified instant
39  /// has occurred.
40  @since(version = 0.2.0)
41  subscribe-instant: func(when: instant) -> pollable;
42
43  /// Create a `pollable` that will resolve after the specified duration has
44  /// elapsed from the time this function is invoked.
45  @since(version = 0.2.0)
46  subscribe-duration: func(when: duration) -> pollable;
47}
48
49/// WASI Wall Clock is a clock API intended to let users query the current
50/// time. The name "wall" makes an analogy to a "clock on the wall", which
51/// is not necessarily monotonic as it may be reset.
52///
53/// It is intended to be portable at least between Unix-family platforms and
54/// Windows.
55///
56/// A wall clock is a clock which measures the date and time according to
57/// some external reference.
58///
59/// External references may be reset, so this clock is not necessarily
60/// monotonic, making it unsuitable for measuring elapsed time.
61///
62/// It is intended for reporting the current date and time for humans.
63@since(version = 0.2.0)
64interface wall-clock {
65  /// A time and date in seconds plus nanoseconds.
66  @since(version = 0.2.0)
67  record datetime {
68    seconds: u64,
69    nanoseconds: u32,
70  }
71
72  /// Read the current value of the clock.
73  ///
74  /// This clock is not monotonic, therefore calling this function repeatedly
75  /// will not necessarily produce a sequence of non-decreasing values.
76  ///
77  /// The returned timestamps represent the number of seconds since
78  /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
79  /// also known as [Unix Time].
80  ///
81  /// The nanoseconds field of the output is always less than 1000000000.
82  ///
83  /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
84  /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
85  @since(version = 0.2.0)
86  now: func() -> datetime;
87
88  /// Query the resolution of the clock.
89  ///
90  /// The nanoseconds field of the output is always less than 1000000000.
91  @since(version = 0.2.0)
92  resolution: func() -> datetime;
93}
94
95@unstable(feature = clocks-timezone)
96interface timezone {
97  @unstable(feature = clocks-timezone)
98  use wall-clock.{datetime};
99
100  /// Information useful for displaying the timezone of a specific `datetime`.
101  ///
102  /// This information may vary within a single `timezone` to reflect daylight
103  /// saving time adjustments.
104  @unstable(feature = clocks-timezone)
105  record timezone-display {
106    /// The number of seconds difference between UTC time and the local
107    /// time of the timezone.
108    ///
109    /// The returned value will always be less than 86400 which is the
110    /// number of seconds in a day (24*60*60).
111    ///
112    /// In implementations that do not expose an actual time zone, this
113    /// should return 0.
114    utc-offset: s32,
115    /// The abbreviated name of the timezone to display to a user. The name
116    /// `UTC` indicates Coordinated Universal Time. Otherwise, this should
117    /// reference local standards for the name of the time zone.
118    ///
119    /// In implementations that do not expose an actual time zone, this
120    /// should be the string `UTC`.
121    ///
122    /// In time zones that do not have an applicable name, a formatted
123    /// representation of the UTC offset may be returned, such as `-04:00`.
124    name: string,
125    /// Whether daylight saving time is active.
126    ///
127    /// In implementations that do not expose an actual time zone, this
128    /// should return false.
129    in-daylight-saving-time: bool,
130  }
131
132  /// Return information needed to display the given `datetime`. This includes
133  /// the UTC offset, the time zone name, and a flag indicating whether
134  /// daylight saving time is active.
135  ///
136  /// If the timezone cannot be determined for the given `datetime`, return a
137  /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
138  /// saving time.
139  @unstable(feature = clocks-timezone)
140  display: func(when: datetime) -> timezone-display;
141
142  /// The same as `display`, but only return the UTC offset.
143  @unstable(feature = clocks-timezone)
144  utc-offset: func(when: datetime) -> s32;
145}
146
147@since(version = 0.2.0)
148world imports {
149  @since(version = 0.2.0)
150  import wasi:io/poll@0.2.6;
151  @since(version = 0.2.0)
152  import monotonic-clock;
153  @since(version = 0.2.0)
154  import wall-clock;
155  @unstable(feature = clocks-timezone)
156  import timezone;
157}
158