Debian Codegraph @

wasi/p3/wit/deps/wasi-clocks-0.3.0-rc-2026-01-06/package.wit

raw
1 package wasi:[email protected];
2
3 /// This interface common types used throughout wasi:clocks.
4 @since(version = 0.3.0-rc-2026-01-06)
5 interface types {
6 /// A duration of time, in nanoseconds.
7 @since(version = 0.3.0-rc-2026-01-06)
8 type duration = u64;
9 }
10
11 /// WASI Monotonic Clock is a clock API intended to let users measure elapsed
12 /// time.
13 ///
14 /// It is intended to be portable at least between Unix-family platforms and
15 /// Windows.
16 ///
17 /// A monotonic clock is a clock which has an unspecified initial value, and
18 /// successive reads of the clock will produce non-decreasing values.
19 @since(version = 0.3.0-rc-2026-01-06)
20 interface monotonic-clock {
21 use types.{duration};
22
23 /// A mark on a monotonic clock is a number of nanoseconds since an
24 /// unspecified initial value, and can only be compared to instances from
25 /// the same monotonic-clock.
26 @since(version = 0.3.0-rc-2026-01-06)
27 type mark = u64;
28
29 /// Read the current value of the clock.
30 ///
31 /// The clock is monotonic, therefore calling this function repeatedly will
32 /// produce a sequence of non-decreasing values.
33 ///
34 /// For completeness, this function traps if it's not possible to represent
35 /// the value of the clock in a `mark`. Consequently, implementations
36 /// should ensure that the starting time is low enough to avoid the
37 /// possibility of overflow in practice.
38 @since(version = 0.3.0-rc-2026-01-06)
39 now: func() -> mark;
40
41 /// Query the resolution of the clock. Returns the duration of time
42 /// corresponding to a clock tick.
43 @since(version = 0.3.0-rc-2026-01-06)
44 get-resolution: func() -> duration;
45
46 /// Wait until the specified mark has occurred.
47 @since(version = 0.3.0-rc-2026-01-06)
48 wait-until: async func(when: mark);
49
50 /// Wait for the specified duration to elapse.
51 @since(version = 0.3.0-rc-2026-01-06)
52 wait-for: async func(how-long: duration);
53 }
54
55 /// WASI System Clock is a clock API intended to let users query the current
56 /// time. The clock is not necessarily monotonic as it may be reset.
57 ///
58 /// It is intended to be portable at least between Unix-family platforms and
59 /// Windows.
60 ///
61 /// External references may be reset, so this clock is not necessarily
62 /// monotonic, making it unsuitable for measuring elapsed time.
63 ///
64 /// It is intended for reporting the current date and time for humans.
65 @since(version = 0.3.0-rc-2026-01-06)
66 interface system-clock {
67 use types.{duration};
68
69 /// An "instant", or "exact time", is a point in time without regard to any
70 /// time zone: just the time since a particular external reference point,
71 /// often called an "epoch".
72 ///
73 /// Here, the epoch is 1970-01-01T00:00:00Z, also known as
74 /// [POSIX's Seconds Since the Epoch], also known as [Unix Time].
75 ///
76 /// Note that even if the seconds field is negative, incrementing
77 /// nanoseconds always represents moving forwards in time.
78 /// For example, `{ -1 seconds, 999999999 nanoseconds }` represents the
79 /// instant one nanosecond before the epoch.
80 /// For more on various different ways to represent time, see
81 /// https://tc39.es/proposal-temporal/docs/timezone.html
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.3.0-rc-2026-01-06)
86 record instant {
87 seconds: s64,
88 nanoseconds: u32,
89 }
90
91 /// Read the current value of the clock.
92 ///
93 /// This clock is not monotonic, therefore calling this function repeatedly
94 /// will not necessarily produce a sequence of non-decreasing values.
95 ///
96 /// The nanoseconds field of the output is always less than 1000000000.
97 @since(version = 0.3.0-rc-2026-01-06)
98 now: func() -> instant;
99
100 /// Query the resolution of the clock. Returns the smallest duration of time
101 /// that the implementation permits distinguishing.
102 @since(version = 0.3.0-rc-2026-01-06)
103 get-resolution: func() -> duration;
104 }
105
106 @unstable(feature = clocks-timezone)
107 interface timezone {
108 @unstable(feature = clocks-timezone)
109 use system-clock.{instant};
110
111 /// Return the IANA identifier of the currently configured timezone. This
112 /// should be an identifier from the IANA Time Zone Database.
113 ///
114 /// For displaying to a user, the identifier should be converted into a
115 /// localized name by means of an internationalization API.
116 ///
117 /// If the implementation does not expose an actual timezone, or is unable
118 /// to provide mappings from times to deltas between the configured timezone
119 /// and UTC, or determining the current timezone fails, or the timezone does
120 /// not have an IANA identifier, this returns nothing.
121 @unstable(feature = clocks-timezone)
122 iana-id: func() -> option<string>;
123
124 /// The number of nanoseconds difference between UTC time and the local
125 /// time of the currently configured timezone, at the exact time of
126 /// `instant`.
127 ///
128 /// The magnitude of the returned value will always be less than
129 /// 86,400,000,000,000 which is the number of nanoseconds in a day
130 /// (24*60*60*1e9).
131 ///
132 /// If the implementation does not expose an actual timezone, or is unable
133 /// to provide mappings from times to deltas between the configured timezone
134 /// and UTC, or determining the current timezone fails, this returns
135 /// nothing.
136 @unstable(feature = clocks-timezone)
137 utc-offset: func(when: instant) -> option<s64>;
138
139 /// Returns a string that is suitable to assist humans in debugging whether
140 /// any timezone is available, and if so, which. This may be the same string
141 /// as `iana-id`, or a formatted representation of the UTC offset such as
142 /// `-04:00`, or something else.
143 ///
144 /// WARNING: The returned string should not be consumed mechanically! It may
145 /// change across platforms, hosts, or other implementation details. Parsing
146 /// this string is a major platform-compatibility hazard.
147 @unstable(feature = clocks-timezone)
148 to-debug-string: func() -> string;
149 }
150
151 @since(version = 0.3.0-rc-2026-01-06)
152 world imports {
153 @since(version = 0.3.0-rc-2026-01-06)
154 import types;
155 @since(version = 0.3.0-rc-2026-01-06)
156 import monotonic-clock;
157 @since(version = 0.3.0-rc-2026-01-06)
158 import system-clock;
159 @unstable(feature = clocks-timezone)
160 import timezone;
161 }