WebAssembly
Avoid nonstandard use of names for types in wit-0.3.0-draft
This is the renaming part of https://github.com/WebAssembly/wasi-clocks/pull/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 https://github.com/WebAssembly/wasi-clocks/issues/69#issuecomment-2204002719, 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 https://github.com/WebAssembly/wasi-clocks/pull/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.
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.
@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 https://github.com/WebAssembly/wasi-clocks/pull/71/commits/8c12295f8d359bb0db936236e10b92fab4723c8c, such as monotonic-time or timestamp.
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.
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.
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).
@ptomato I'm getting back to this now. You need to keep the old types and add the @deprecated tag to them.
The docs can be found here: feature-gates
@bakkot I'm sorry I should have tagged you in that last comment.
This PR needs to keep the old types and add the @deprecated tag to them.
The docs can be found here: feature-gates
My preference would be to move all of this work to the 0.3.0 draft with 0.3.0 around the corner.
@ricochet This PR does currently target 0.3.0.
@cdmurph32 Assuming this is going for 0.3.0 and not 0.2.8, does it still need @deprecated tags? All the types touched by this PR are already (prior to this PR) tagged as @since(version = 0.3.0) or @unstable(feature = clocks-timezone).
That's great. The only question I have is whether we want the README to reflect the draft 0.3.0 types yet, but that doesn't really matter much.
@ricochet I don't have the ability to merge yet.
@cdmurph32 To be clear, this does touch or remove many types which existed in 0.2.X. It's just that the 0.3.0 draft tags all of those as @since(version = 0.3.0). I don't know if that's because 0.3 counts as a major bump or what.
@bakkot @ricochet
That's fine. Are we happy with the timezone interface? Should we remove @unstable from it?
For 0.2.* interfaces with unstable gates, it would need to go through the phase process before removing @unstable. Since this is 0.3 and will be brought forward for stabilization vote as a whole, it would be ok IMO to remove it and deprecation gates in the 0.3 version.
The decision for dropping the unstable flag should be whether or not it is stable for 0.3 implementers aka has the timezone API been implemented by a runtime and the champions of this proposal intend for it to be considered a stable part of the 0.3 wasi-clocks API?
Perhaps we should hold off then on removing unstable. I'll add/verify timezone support in the runtime(s) first.
Note that in https://github.com/WebAssembly/WASI/issues/688#issuecomment-2219214001 we were also discussing changes to the timezone interface. I would personally like to see those resolved before graduating it to stable.
If you're interested in those changes I could prepare a PR, though I'm not a timezone expert and so would need @ptomato or someone to review.
@bakkot @ptomato I'm unsure what we are waiting on to merge this. Do you want to add more of your timezone changes from https://github.com/WebAssembly/wasi-clocks/pull/71 first? Or can we go ahead and merge now?
@cdmurph32 This is ready to go from my perspective. I've just rebased (again - the thing where the @since annotation gets automatically updated sure does make for a lot of merge conflicts).
I think the changes in https://github.com/WebAssembly/wasi-clocks/pull/71 layer cleanly on top of this and can go in separately.