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

bakkot · 2025-01-30T23:53:30Z

This is the renaming part of #71 by @ptomato applied to the new wit-0.3.0-draft directory. (Edit: as well as some other changes prompted by discussion below.)

As discussed in #69 (comment), the use of the terms "wall clock" and "instant" here is very confusing: in JavaScript, Java, Go, and etc, an "instant" is a particular absolute point in time, and "wall clock" time means a local time without associated timezone and therefore not referring to a particular point in time. (More on this topic in the excellent Temporal docs.)

By contrast, here "instant" does not refer to a particular absolute point in time, and "wall clock" time is used to mean a particular absolute point in time. I'm hoping this can be fixed to use the more conventional names.

(There's also a couple of // NOTE comments about weird types.)

Note also that #71 contains proposed changes to the unstable timezone interface. I'd be very happy to rebase those onto wit-0.3.0-draft as well, if you'd like, though note that per the final paragraph of this comment the interface probably needs at least one additional method than is currently included in that PR.

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

README.md

pchickey · 2025-01-31T01:32:55Z

wit-0.3.0-draft/system-clock.wit

+    resolution: func() -> instant;
+    // NOTE: This return value doesn't represent an exact time, so maybe is not
+    // a correct use of the Instant type. Would it make sense to have a
+    // system-clock::duration analogous to monotonic-clock::duration?


Yes, I agree there should be a duration type in system-clock, can you add one?

Done.

It's a little silly to use a seconds+nanoseconds struct for this given that a u64 of nanoseconds can represent durations up to 585 years and system clock resolution is normally going to be at most 16 milliseconds. Even a u32 of nanoseconds (~4 seconds) would probably suffice. But system-clock:duration is the most conceptually correct type and this is not going to be on the critical path anywhere, so it shouldn't really matter. And it does match clock_getres.

pchickey · 2025-01-31T01:48:53Z

Thank you for making this change to align us with the Temporal proposal.

One aspect I am a little skeptical of is the change of monotonic-clock.instant to be named monotonic-clock.monotonic-clock-point. That name feels a bit unwieldy, is there prior art for that name? The monotonic clock comes from POSIX where the value type is named struct timespec, but that particular name is a perfect example of POSIX picking a poor name for their own reasons, which I don't feel

Could the value given by monotonic-clock.now still be a type named instant, which is distinct from system-clock.instant by their namespace? My reading, is that this monotonic-clock-point concept means something very closely related to Temporal.Instant ("only stores exact time and no other information"), with the distinguishing difference from system-time.instant that there is no way to map it to any sort of time zone or calendar system.

ptomato · 2025-01-31T01:56:02Z

@bakkot suggested monotonic-clock-point here to try to avoid overloading the term instant. I don't know if he had any prior art in mind, but I suggested a few alternatives in 8c12295, such as monotonic-time or timestamp.

bakkot · 2025-01-31T03:29:39Z

I'm OK with overloading "instant" if that's the best option but would prefer not to given an acceptable alternative. Also it would be a little weird to have system clock "instant"s be a struct but have monotonic clock "instant"s be a u64.

Unfortunately there's not a lot of good prior art for the return value of a monotonic clock; other languages mostly just return a long or similar.

Names I'm aware of for things vaguely in this space:

Rust: "Instant"
Posix: "timespec"
Windows: "tick" as in GetTickCount
Dart: "tick" as in GetCurrentMonotonicTicks
C++: "time_point"
Swift: "DispatchTime"
Kotlin: "TimeMark" (or specifically "TimeMarkValue" for the monotonic clock)
Nim: "MonoTime"

I don't like "instant" because it's overloaded; I don't like names with "time" because these aren't really times per se, just values which can be diffed to get a duration; I don't like "tick" because the length of a "tick" is usually system-dependent. I suggested "clock point" because this represents just a point on a particular clock, nothing more or less. But these are just my personal opinions.

Other than "clock point", I think my favorite name would be "mark", following Kotlin: I think the name reasonably suggests that you can take the difference between two marks but that they don't have any meanings on their own.

pchickey · 2025-02-03T17:47:29Z

Thanks for looking at the field of choices there. I would be fine with using anything we can reasonably justify as following at least some other existing use of a term, rather than inventing our own. On aesthetics I also like kotlin's "mark" for this use.

bakkot · 2025-02-03T18:47:10Z

OK, switched to "mark" for the moment, pending anyone having a better idea.

"mark" does also have some similarity to the web's performance.mark(), which also gives you values from a monotonic clock, although there's several differences (such as the marks being named and in milliseconds rather than nanoseconds).

sunfishcode

Using "mark" in place of the monotonic clock's "instant", and "instant" in place of the wall clock's "datetime" seem fine to me.

wit-0.3.0-draft/system-clock.wit

sunfishcode · 2025-02-04T18:27:48Z

wit-0.3.0-draft/system-clock.wit

    @since(version = 0.3.0)
-    record datetime {
+    record instant {
        seconds: u64,


This is pre-existing, however while you're here, could you also change seconds from u64 to s64? That better reflects the operating system APIs that it will be commonly implemented on, and supports timess from before 1970.

Done. What about for durations? Is it intentional that durations cannot be negative? (See also tc39/proposal-temporal#558.)

Note that making durations potentially negative for the monotonic clock is somewhat tricky unless mark is also changed to use s64, because the difference between the largest u64 and 0 is not representable as an s64 and hence a s64 duration would not be able to represent all possible differences between two marks.

(In practice this will never come up because no one is going to observe monotonic clock values which are 294 years apart, so I guess implementations could trap or something.)

Right now, wasi-clocks has a much smaller surface area than Temporal, and it doesn't have any uses for negative durations. However, I'd be open to using a signed type. I think we could go either way. If it's signed, we just need to make sure we document that things like resolution don't return negative values, and document what subscribe-durection does given a negative value.

Mostly I ask because the readme has an example of a language creating a duration by subtracting two values from the clock, and it's not clear what the behavior would be if they'd reversed the order of those values. If the answer is "that's on the language to figure out" that's fine by me.

Yes, the current design is that that's on the language to figure out.

sunfishcode · 2025-02-04T18:30:08Z

wit-0.3.0-draft/system-clock.wit

-/// 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.


We originally avoided the term "system clock", but I think it's ok to use now.

Background: we wanted WASI to deemphasize the idea of "the system", because that may suggest a level of monolithicity that we don't want to require. However, if "wall clock" isn't suitable, I'm guessing we won't find any other names that have the desired meaning without risk of being mistaken. So unless we think of some brilliant alternative name, I think "system clock" is the least-problematic option.

ptomato · 2025-02-04T20:10:52Z

wit-0.3.0-draft/system-clock.wit

+        seconds: s64,
        nanoseconds: u32,


This is correct IMO, but might be worth a note that nanoseconds are unsigned because even negative seconds values are still conceptually "positive" exact times.

Oh, I was just thinking of this as, the way you'd represent one nanosecond before the epoch would be { -1 seconds, +999_999_999 nanoseconds }.

I'm not sure what you mean by 'conceptually "positive" exact times'.

Agreed, I think of it in the same way as you. What I meant is Dec 31 1969 isn't "negative" in any way other than being before the epoch, which is arbitrary.

The (wrong) alternative interpretation would be to think of { seconds, nanoseconds } as a "duration" before the epoch, e.g. -1.999999999 nanoseconds. That would result in Dec 31 1969 23:59:58.000000001.

Added a note which hopefully clarifies:

Note that even if the seconds field is negative, incrementing nanoseconds always represents moving forwards in time. For example, { -1 seconds, 999_999_999 nanoseconds } represents the instant one nanosecond before the epoch.

ptomato · 2025-02-04T20:11:18Z

wit-0.3.0-draft/system-clock.wit

@@ -47,6 +47,7 @@ interface system-clock {

    /// Query the resolution of the clock.
    ///
+    /// The seconds field of the output is always positive.


Suggested change

/// The seconds field of the output is always positive.

/// The seconds field of the output is always positive or zero.

Thanks for catching this. Actually this note is unnecessary unless we're making durations signed, so I'll just remove it for now but if it goes back I'll fix this.

bakkot · 2025-02-12T19:58:25Z

Any more to do here?

cdmurph32 · 2025-03-20T16:23:05Z

@yoshuawuyts: Should this target 0.2.5 using @deprecated?

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

b7d7920

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

bakkot force-pushed the clocks-improvements-on-three branch from ec27938 to b7d7920 Compare January 31, 2025 00:32

pchickey reviewed Jan 31, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

pchickey reviewed Jan 31, 2025

View reviewed changes

address duration-related notes

c8c0547

s/clock point/mark/g

2b4dc70

bakkot mentioned this pull request Feb 3, 2025

feat(wasi): add support for wasi:[email protected] bytecodealliance/wasmtime#10063

Draft

sunfishcode reviewed Feb 4, 2025

View reviewed changes

address sunfishcode feedback

021a58d

ptomato reviewed Feb 4, 2025

View reviewed changes

bakkot added 2 commits February 4, 2025 12:46

more feedback

24e32c3

drop underscores from number literal

21f44f1

pchickey requested a review from sunfishcode February 12, 2025 20:10

bakkot mentioned this pull request Mar 18, 2025

Changes to timezones API #69

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

bakkot commented Jan 30, 2025 •

edited

Loading

pchickey Jan 31, 2025

bakkot Jan 31, 2025

pchickey commented Jan 31, 2025

ptomato commented Jan 31, 2025

bakkot commented Jan 31, 2025

pchickey commented Feb 3, 2025

bakkot commented Feb 3, 2025

sunfishcode left a comment

sunfishcode Feb 4, 2025

bakkot Feb 4, 2025

bakkot Feb 4, 2025

sunfishcode Feb 4, 2025

bakkot Feb 4, 2025

sunfishcode Feb 4, 2025

sunfishcode Feb 4, 2025

ptomato Feb 4, 2025

bakkot Feb 4, 2025

ptomato Feb 4, 2025

bakkot Feb 4, 2025

ptomato Feb 4, 2025

bakkot Feb 4, 2025

bakkot commented Feb 12, 2025

cdmurph32 commented Mar 20, 2025

	/// The seconds field of the output is always positive.
	/// The seconds field of the output is always positive or zero.

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

Are you sure you want to change the base?

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

Conversation

bakkot commented Jan 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pchickey commented Jan 31, 2025

ptomato commented Jan 31, 2025

bakkot commented Jan 31, 2025

pchickey commented Feb 3, 2025

bakkot commented Feb 3, 2025

sunfishcode left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bakkot commented Feb 12, 2025

cdmurph32 commented Mar 20, 2025

bakkot commented Jan 30, 2025 •

edited

Loading