SE-0329 (Second Review): Clock, Instant, and Duration

[xwu (Xiaodi Wu)]

@Karl

Could we not work-around the leap seconds issue by introducing a SystemClock , as the system's notion of the current time, with whatever leap seconds handling it has. I don't know of any other languages' standard libraries which provide access to monotonic clocks and uptime clocks but not the system's reckoning of the current time. Do you know of any?

We could avoid the naming issues for now by simply referring to it as SystemClock.Instant . It could later be given a nicer name, such as Timestamp .

There are a lot of libraries which parse timestamps and need the ability to return those values as a convenient type. For example, async-http-client parses cookie expiration times, and UniqueID is able to extract the embedded timestamps from time-ordered UUIDs.

Whilst Foundation has split off FoundationNetworking and FoundationXML as separate modules, Date still lives in the main Foundation library, alongside types such as Calendar and DateFormatter which themselves depend on ICU. With the standard library now having dropped ICU, importing Foundation just to have Date as a currency type comes with a higher cost than ever before.

If this doesn't make it in to the standard library, it is inevitable that 3rd-party packages will step in to fill the gap. But that is not a better outcome for the Swift ecosystem, IMO - we would be better-served by a currency type which lives in the standard library. Providing those currency types is, after all, one of the standard library's main jobs.

IMO, defining the Clock protocol but leaving the system clock to other packages is like defining the Collection protocol but asking developers to bring their own Array .

As I’d commented before during the pitch phase, this seems appropriate for a setup analogous to URL remaining in Foundation and FilePath coming up in Swift System.

[Philippe_Hausler]

@divanise

I also find the tolerance: .none construct confusing. I'd instead suggest something along these lines for that functionality:

protocol Clock {
  func sleep(until deadline: Instant, tolerance: Instant.Duration) async throws 

  var defaultTolerance: Instant.Duration { get }
}

extension Clock {
  func sleep(until deadline: Instant) async {
    sleep(until: deadline, tolerance: .defaultTolerance)
  }
}

To be clear; this approach is not possible since the default tolerances are not a knowable value since they are determined at runtime (potentially at layers that processes don't even have access to). On Darwin for example, the kernel decides what the unspecified tolerance is for timers based on QoS and many other factors. To actually extract that number; the calling process needs root level privileges - so I don't think we can feasibly expose that as an actual value.

[divanise (Daniel Ivanisevic)]

Right, of course. Sorry about that, I find it hard to remember all the various protocol requirements without Xcode running nearby.

[George]

@Philippe_Hausler

To be clear; this approach is not possible since the default tolerances are not a knowable value since they are determined at runtime

Sorry if this has been brought up already, but couldn't Tolerance be an enum with cases default and specified(Duration)?

[tera]

@Philippe_Hausler

To be clear; this approach is not possible since the default tolerances are not a knowable value since they are determined at runtime (potentially at layers that processes don't even have access to). On Darwin for example, the kernel decides what the unspecified tolerance is for timers based on QoS and many other factors. To actually extract that number; the calling process needs root level privileges - so I don't think we can feasibly expose that as an actual value.

You can allocate a certain duration constant value (e.g. all bits set) to represent default duration value, no? And if the notion of infinite duration is needed it can be modelled as, say, next smaller number (or vice versa).

[divanise (Daniel Ivanisevic)]

@Philippe_Hausler

To be clear; this approach is not possible since the default tolerances are not a knowable value since they are determined at runtime (potentially at layers that processes don't even have access to).

Ah, got it. That's unfortunate from the perspective of the API client, but an awesome implementation detail. Would something along the lines of a maxDefaultTolerance be feasible? I have a hard time envisioning a situation where I'd be ok with asking for the default tolerance without having an idea of what that tolerance is. I'm more likely to end up requiring explicit tolerances via code review or linter rules.

That aside, I'd much rather see a dedicated interval enum as suggested upthread rather than reusing Optional, although with a variation:

enum DurationTolerance<Duration : DurationProtocol> {
   case default
   case zero
   case scaled(Double) 
   case fixed(Duration) 
}

The .scaled case would allow expressing things like a tolerance of 5% of the requested sleep duration.

EDIT: Clarified that I find it unfortunate that the default tolerance can't be known precisely, rather than that it's dynamic.

[Karl]

@xwu

As I’d commented before during the pitch phase, this seems appropriate for a setup analogous to URL remaining in Foundation and FilePath coming up in Swift System.

They are really nothing alike.

A URL type does not belong in the standard library, because there is (ironically) no universal interpretation of URLs. It may, to an outsider, seem like a solved problem, but in truth, it is anything but.

FilePath could potentially be moved to the standard library, although it would require a filesystem (which compilation targets such as Wasm do not support) and it would be unique in that it, by design, behaves entirely differently on every platform. I don't know of any other standard library interface which does that. For that reason, I personally wouldn't support moving it, were it to be proposed.

A type which represents a duration from an epoch is not like either of those things. It is a pure, abstract concept, and one which we very much need in the standard library. Leaving it to the package ecosystem is a much, much worse alternative and a severe compromise.

And those packages will exist on the very day this proposal is accepted. By not including it, we're only creating needless division and awkwardness for developers.

[Philippe_Hausler]

Do folks think that a reasonable approach would be to have clock define its requirements as two methods instead? that way we avoid the .none case?

  func sleep(until deadline: Instant) async throws
  func sleep(until deadline: Instant, tolerance: Instant.Duration) async throws

That way developers using that would either pose a tolerance or not, no passing of nil or .none allowed.

[divanise (Daniel Ivanisevic)]

I'd be happy with that, so long as the documentation made it clear that there's a difference between not specifying a tolerance and specifying a tolerance of .zero. If there is a difference anyway; presumably that would vary from implementation to implementation.

I'd still like to see a maxDefaultTolerance or similar static property on Clock, though.

[bzamayo (Benjamin Mayo)]

I don't think it's terrible but instinctively I think it's a bit of a footgun. Without looking up documentation, I'd assume the sleep(until: date) version is equivalent to no tolerance as in 'tolerance of zero' rather than a 'default' pliable tolerance. It also might engender the reverse confusion where people call sleep(until: date, tolerance: .zero) because that feels most natural when typing it out, even though they don't actually need the exactness and would benefit from the energy efficient default tolerance.

(IMHO the 'infinite'/'indefinite' static var would be the preferable design then, assuming the enum design is out of the question for memory space reasons as stated upthread.)

[Philippe_Hausler]

@divanise

I'd still like to see a maxDefaultTolerance or similar static property on Clock , though.

I will have to dig into that a bit, but from what I understand of the kernel scheduling side of things for Darwin that value is highly dependent and likely even the maximum may not be determinable as a static value.

[divanise (Daniel Ivanisevic)]

Fair enough, but I have to imagine there's at least a reasonable confidence interval. If the tolerance can regularly be anywhere from milliseconds to days, then asking for the default feels more like a footgun than an API to me.

(Of course, coming with a succinct property name for "the maximum default tolerance, 19 times out of 20" would be a challenge on its own... )

If it's not easily expressible via an API, then I think adding a note to the sleep method's documentation with the intended tolerance range should be mandatory, similar to how most of the collections API methods give big-O estimates of their performance.

[xwu (Xiaodi Wu)]

@Karl

A type which represents a duration from an epoch is not like either of those things. It is a pure, abstract concept, and one which we very much need in the standard library.

Unfortunately—and this was the crux of the problem leading up to this version of the proposal—duration from an epoch is reckoned differently on the different platforms, and there is no universal interpretation of that duration. It may, to an outsider, seem like a solved problem, but in truth, it is anything but. A SystemClock would, by design, also behave differently on every platform. It is for those reasons that I drew the analogy to URL and FilePath.

[ksluder (Kyle Sluder)]

@divanise

Fair enough, but I have to imagine there's at least a reasonable confidence interval.

Not on a system under immense load.

[benlings]

Allowing the tolerance API to express a fraction of the duration seems like a useful addition. For example the NSTimer API docs say:

As the user of the timer, you can determine the appropriate tolerance for a timer. A general rule, set the tolerance to at least 10% of the interval, for a repeating timer.

[divanise (Daniel Ivanisevic)]

@ksluder

Not on a system under immense load.

Oh, I absolutely agree.

On the one hand, that's why I referred to the default tolerance as having a confidence interval. On the other, that's an issue even if you request a specific tolerance instead of the default, so I've been thinking of that as covered by sleep's "best effort" contract rather than specific to tolerances (default or otherwise).

[divanise (Daniel Ivanisevic)]

And something that slipped my mind when I suggested a fractional tolerance is that there are two sleep methods in the proposal, Task.sleep(for: Duration) and Clock.sleep(until: Instant). I was only thinking of the former when I suggested specifying a tolerance as a ratio of the duration and completely forgot to consider the latter.

In any case, I think @Philippe_Hausler's idea about using separate overloads for default vs explicit tolerances is a simpler, better approach than an enum, whether that enum is Optional or a new DurationTolerance.

[tera]

@Philippe_Hausler

Do folks think that a reasonable approach would be to have clock define its requirements as two methods instead? that way we avoid the .none case?

  func sleep(until deadline: Instant) async throws
  func sleep(until deadline: Instant, tolerance: Instant.Duration) async throws

That way developers using that would either pose a tolerance or not, no passing of nil or .none allowed.

That's fine, but you would still want to have an ability to call the first version via the second (I believe). tolerance values won't be huge in practice (e.g. why would anyone want to write (pseudocode) sleep(until: now + 10 sec, tolerance: 10e9 sec). You may use some bit patterns to represent special values like default or critical etc.

[Philippe_Hausler]

@tera

You may use some bit patterns to represent special values like default or critical etc.

The problem with bit patterns is that those need to have either a saturation or overflow behavior. For example if one gets a tolerance value the immediate expectation is that you add said tolerance (in custom clocks) to the deadline to find the maximum deadline that is acceptable.

The advantage to either a nil or a second required method is that it guides the implementor of the clock to instead search for the nearest next scheduled deadline and coalesce that event together without performing math using the tolerance values. That nearest neighbor search is done within some default tolerance derived by some level of work-load. Hence why an actual reported value may be totally non-deterministic or observable except in privileged processes for stuff that uses libdispatch to schedule work.

@benlings

Allowing the tolerance API to express a fraction of the duration seems like a useful addition. For example the NSTimer API docs say:

I think the better documentation to reference is the leeway on dispatch. schedule(deadline:repeating:leeway:) | Apple Developer Documentation which states that:

The first time the timer fires, the maximum allowable delay is equal to the value in the leeway parameter. For subsequent firings of a repeating timer, the timer fires at deadline + (n * repeating) , and the maximum delay is equal to min(leeway, repeating/2) —that is, the smaller of either the leeway value or half the value in the repeating parameter.

But for cooperative dispatch queues (the thing powering concurrency) this leeway isn't really the same per scheduling - Darwin targets are able to convey more detailed information to the kernel with these specialized queues so the leeway calculations are a bit different. Particular to Darwin's kernel optimizations, Apple Silicon devices take a bit more of the tolerances into account and are able to more efficiently schedule work, Intel chips on the other hand have a slight more importance for battery life to make sure those leeway values are suitable to coalesce work due to their p-state bring up power requirements.

Linux x86_64 machines (if I understand the scheduling behavior of libdispatch correctly) will behave closer to the Intel Mac machines.

[Karl]

@xwu

Unfortunately—and this was the crux of the problem leading up to this version of the proposal—duration from an epoch is reckoned differently on the different platforms, and there is no universal interpretation of that duration. It may, to an outsider, seem like a solved problem, but in truth, it is anything but. A SystemClock would, by design, also behave differently on every platform. It is for those reasons that I drew the analogy to URL and FilePath .

A duration from an epoch is a universal, abstract concept. At any one instant, different systems may consider the current time to be different for any number of reasons - but it is not necessarily a question of the platform; the user may have just set the clock manually. That is inherent to the notion of a system clock.

But it is also irrelevant - the system clock does not need to define those details in order to be the governor of determining which instants should be considered as being in the past, present, or future.

It is nothing at all like URL or FilePath. Again, URL does not behave differently on each platform; it lacks a single accepted specification on any platform. If it did, it would be a good candidate for the standard library. The problem is with the standards, not the concept.

And again, FilePath is (a little) better in that regard, but it has very little utility if you don't know how the platform behaves. That is very different to SystemClock, where its core behaviour is still very much usable without needing to care about intricacies such as leap seconds. It may, to an outsider, seem like an appropriate analogy, but in truth, it is anything but.

For the ultimate proof, look no further than the fact that Foundation is promising to add that API anyway. So there is literally zero gain here - the concept will still be shipped in the toolchain and widely available to Swift developers, just with an enormous cost (depending on Foundation) that doesn't need to be there. If it really was a terrible or flawed concept, or impossible to implement, Foundation would not be promising to implement it and make it widely available.

The standard libraries of plenty of other languages have these features built in. We also need them in Swift. But as it stands, Swift is going to be alone in lacking this feature.