| 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 |
} |