From 920b60d6a30b4e93efc5d7377220eab840bb4bd2 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Tue, 31 Oct 2023 11:59:10 -0700 Subject: [PATCH] Introduce monotonic-clock duration (#53) * monotonic clock: introduce `duration` type, split `subscribe` We are introducing a `duration` type because it has a distinct meaning from `instant`: an `instant` can only be compared to other `instant`s from the exact same `monotonic-clock`, whereas a `duration` represents a duration of time which can be compared to any other duration of time. The `duration` type is motivated, in part, by a desire to reuse it to specify durations such as timeouts in other WASI proposals. Instead of taking a boolean specifying whether the u64 is an absolute or relative time, `subscribe-instant` takes an `instant` type and `subscribe-duration` takes a `duration` type. * generate markdown --- imports.md | 35 ++++++++++++++++++++++++++--------- wit/monotonic-clock.wit | 26 +++++++++++++++++++------- 2 files changed, 45 insertions(+), 16 deletions(-) diff --git a/imports.md b/imports.md index f82d3c1..1ec1fbe 100644 --- a/imports.md +++ b/imports.md @@ -62,7 +62,12 @@ successive reads of the clock will produce non-decreasing values.

#### `type instant` `u64` -

A timestamp in nanoseconds. +

An instant in time, in nanoseconds. An instant is relative to an +unspecified initial value, and can only be compared to instances from +the same monotonic-clock. +

type duration

+

u64

+

A duration of time, in nanoseconds.

Functions

now: func

@@ -74,22 +79,34 @@ produce a sequence of non-decreasing values.

  • instant

    • resolution: func

    -

    Query the resolution of the clock.

    +

    Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.

    +
    Return values
    + +

    subscribe-instant: func

    +

    Create a pollable which will resolve once the specified instant +occured.

    +
    Params
    +
    Return values
    -

    subscribe: func

    -

    Create a pollable which will resolve once the specified time has been -reached.

    +

    subscribe-duration: func

    +

    Create a pollable which will resolve once the given duration has +elapsed, starting at the time at which this function was called. +occured.

    Params
    Return values

    Import interface wasi:clocks/wall-clock

    WASI Wall Clock is a clock API intended to let users query the current diff --git a/wit/monotonic-clock.wit b/wit/monotonic-clock.wit index d9ac7cb..afacdbb 100644 --- a/wit/monotonic-clock.wit +++ b/wit/monotonic-clock.wit @@ -11,22 +11,34 @@ interface monotonic-clock { use wasi:io/poll.{pollable}; - /// A timestamp in nanoseconds. + /// An instant in time, in nanoseconds. An instant is relative to an + /// unspecified initial value, and can only be compared to instances from + /// the same monotonic-clock. type instant = u64; + /// A duration of time, in nanoseconds. + type duration = u64; + /// Read the current value of the clock. /// /// The clock is monotonic, therefore calling this function repeatedly will /// produce a sequence of non-decreasing values. now: func() -> instant; - /// Query the resolution of the clock. - resolution: func() -> instant; + /// Query the resolution of the clock. Returns the duration of time + /// corresponding to a clock tick. + resolution: func() -> duration; - /// Create a `pollable` which will resolve once the specified time has been - /// reached. - subscribe: func( + /// Create a `pollable` which will resolve once the specified instant + /// occured. + subscribe-instant: func( when: instant, - absolute: bool + ) -> pollable; + + /// Create a `pollable` which will resolve once the given duration has + /// elapsed, starting at the time at which this function was called. + /// occured. + subscribe-duration: func( + when: duration, ) -> pollable; }