# µPitch - SuspendingClock and ContinuousClock epochs

**URL:** <https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017>\
**Category:** Pitches\
**Created:** [February 21, 2025, 7:48pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017 "2025-02-21T19:48:39Z")\
**Posts on this page:** 14\
**Page:** 1

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [February 21, 2025, 7:48pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/1 "2025-02-21T19:48:39Z")

</div>

[The proposal for Clock, Instant and Duration](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0329-clock-instant-duration.md) brought in two primary clock types: `SuspendingClock` and `ContinuousClock`. These both have a concept of a reference point for their `Instant` types.

Not all clocks have a starting point, however in these cases they do. Generally, it cannot required for a clock's instant definition to have a start or the start may not be a fixed point. However it can be useful that a given instant can be constructed to determine the elapsed duration from the starting point of that clock if it does have it.

Two new properties will be added, one to `SuspendingClock` and another to `ContinuousClock`. Both of these properties will be the epoch for which all `Instant` types are derived from; practically speaking this is the "zero" point for these clocks.

```swift
extension ContinousClock {
    public var epoch: Instant { get }
}

extension SuspendingClock {
    public var epoch: Instant { get }
}

```

These can be used to gather information like for example the uptime of a system, or the active time of a system;

```swift
let clock = ContinousClock()
let uptime = clock.now - clock.epoch

```

Or likewise;

```swift
let clock = SuspendingClock()
let activeTime = clock.now - clock.epoch

```

It was considered to add a constructor or static member to the `SuspendingClock.Instant` and `ContinousClock.Instant` however the home on the clock itself provides a more discoverable and nameable location.

This is a purely additive change and provides no direct impact to existing ABI. It only carries the ABI impact of new properties being added to an existing type.

It is suggested that this be used as an informal protocol for other clocks. It was considered as an additional protocol but that was ultimately rejected because no generic function made much sense that would not be better served with generic specialization or explicit clock parameter types.

---

<div class="post-metadata">

**Author:** ![Jon\_Shier](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jon_shier/32/921_2.png) [@Jon\_Shier](https://forums.swift.org/u/Jon_Shier)\
**Post date:** [February 21, 2025, 7:51pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/2 "2025-02-21T19:51:34Z")

</div>

Ooo, how back deployable would this be? Alamofire is using a "restricted" API for system uptime I'd really like to replace.

---

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [February 21, 2025, 7:54pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/3 "2025-02-21T19:54:03Z")

</div>

That has yet to be determined how that will be done, but they are very simple... so it is not horribly complicated to do so - that is an implementor discretion thing so id rather focus on the usefulness, functionality and naming rather than getting into the weeds with that part just yet.

If it were up to me 100%; I would not be opposed to the idea of back deploying the back to the introduction of the clocks. But it needs some additional (out of this uPitch discussion first).

---

<div class="post-metadata">

**Author:** ![John\_McCall](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/john_mccall/32/1351_2.png) [@John\_McCall](https://forums.swift.org/u/John_McCall)\
**Post date:** [March 17, 2025, 8:37pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/4 "2025-03-17T20:37:25Z")

</div>

It's strange to me that this proposal says that these clocks have well-defined epochs but doesn't actually document what those epochs are. The examples imply that the epoch is based on the system boot time; is that a portable guarantee?

---

<div class="post-metadata">

**Author:** ![grynspan](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/grynspan/32/15315_2.png) [@grynspan](https://forums.swift.org/u/grynspan)\
**Post date:** [March 17, 2025, 8:46pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/5 "2025-03-17T20:46:04Z")

</div>

Could have sworn I'd commented before but yes, please add this API! We currently do something gnarly in Swift Testing to simulate the epoch.

---

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [March 17, 2025, 9:47pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/6 "2025-03-17T21:47:21Z")

</div>

The epoch definitions are zero's. This is portable to all cases where the clocks are implemented (other system implementations may be different I guess... but honestly im not sure how anyone would define the system epoch any differently).

---

<div class="post-metadata">

**Author:** ![John\_McCall](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/john_mccall/32/1351_2.png) [@John\_McCall](https://forums.swift.org/u/John_McCall)\
**Post date:** [March 17, 2025, 10:48pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/7 "2025-03-17T22:48:23Z")

</div>

The current proposal says that these clocks have meaningful starting times, but then it doesn't document anything about what that starting time means. That seems hard to use without making extra assumptions! For all the user knows, this is measured relative to the process launch or to January 1st, 1970.

It sounds like the intent is that this matches the system epoch used by `CLOCK_MONOTONIC` and similar system timing facilities. Among other things, that makes it a useful way of measuring time across processes / system logs. That seems like something the proposal should document (maybe with a note that typical systems align that with the boot time), and maybe it should also inform the property name.

If there's a system that doesn't have a meaningful system-wide epoch, it's probably better to not provide this API there than to provide it with radically different semantics.

---

<div class="post-metadata">

**Author:** ![jrose](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jrose/32/408_2.png) [@jrose](https://forums.swift.org/u/jrose)\
**Post date:** [March 17, 2025, 10:59pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/8 "2025-03-17T22:59:45Z")

</div>

See also a similar discussion on the Rust side, where they (originally) very explicitly decided _not_ to make their SuspendingClock equivalent have a semantic epoch.

> **[OS-Specific Extensions for creating Instant](https://internals.rust-lang.org/t/os-specific-extensions-for-creating-instant/22408)**
>
> I'm working with OS-level UDP packet timestamps in FreeBSD. In general this is a feature (SO\_TIMESTAMP) in some operating systems that lets you access the time that the OS received a packet -- as opposed to when your application called recv() for...

---

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [March 18, 2025, 5:52pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/9 "2025-03-18T17:52:45Z")

</div>

> [@John\_McCall](#):
>
> It sounds like the intent is that this matches the system epoch used by `CLOCK_MONOTONIC` and similar system timing facilities.

Correct; this should NOT be applied to any other clocks that do not have a stable or defined.  
I definitely think that adding documentation to this effect is reasonable and warranted. The name was chosen because this is to be the point of starting measuring. Which for example the pitch for the `UTCClock` does have a non-zero instant as it's epoch. But measuring the differential between this gives something different of a use - for the suspending and continuous cases (both derived system types from similar timing to monotonic clocks) the resultant of the difference between the now and the epoch is the active uptime and the total uptime respectively. Whereas the `UTCClock` case is not a boot point but instead a reference for which all time is derived; which is more useful for the cases of serialization and conversion to foreign systems. In the `UTCClock` case that would share the same value across backing implementations; all UTCClock.epoch values on all platforms would return Jan 1 2001 since that is how we implement the underlying storage of `Date`.

> [@jrose](#):
>
> See also a similar discussion on the Rust side, where they (originally) very explicitly decided _not_ to make their SuspendingClock equivalent have a semantic epoch.

From my admittedly limited understanding, the differential here is that ContinuousClock.Instant by construction cannot be compared to SuspendingClock.Instant whereas Rust has a singular Instant type shared for all clocks. From a Swift perspective you may be able to get a shared duration differential between two instants from two clocks, but instead of the types being congruent you have to do some hoop jumping (which to be honest is possible today... but is rather distasteful and gives questionable answers).

I would be amenable to restricting all future platform implementations to have a reference epoch for the suspending and continuous clocks as a Duration 0 and adjust the implementation of the now for those platforms to be referent to that. But since those types are relatively opaque (not allowing direct access to their members) it does not seem to have the practical costs of the type ambiguity that Rust seems to suffer here.

In short; if someone subtracts two SuspendingClock.Instants, extracts the components, converts to fractional seconds and adds that value to a Date; that is programmer error.

---

<div class="post-metadata">

**Author:** ![John\_McCall](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/john_mccall/32/1351_2.png) [@John\_McCall](https://forums.swift.org/u/John_McCall)\
**Post date:** [March 18, 2025, 6:42pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/10 "2025-03-18T18:42:11Z")

</div>

> [@Philippe\_Hausler](#):
>
> Correct; this should NOT be applied to any other clocks that do not have a stable or defined.  
> I definitely think that adding documentation to this effect is reasonable and warranted. The name was chosen because this is to be the point of starting measuring. Which for example the pitch for the `UTCClock` does have a non-zero instant as it's epoch. But measuring the differential between this gives something different of a use - for the suspending and continuous cases (both derived system types from similar timing to monotonic clocks) the resultant of the difference between the now and the epoch is the active uptime and the total uptime respectively. Whereas the `UTCClock` case is not a boot point but instead a reference for which all time is derived; which is more useful for the cases of serialization and conversion to foreign systems. In the `UTCClock` case that would share the same value across backing implementations; all UTCClock.epoch values on all platforms would return Jan 1 2001 since that is how we implement the underlying storage of `Date`.

Okay, documenting that it matches other platform-defined concepts of the epoch on specific platforms sounds good to me.

I guess my remaining question is whether "epoch" alone is such a clear term of art in this domain that it's a reasonable property name. It certainly doesn't seem like there's any value in having a consistent property name across these clocks and `UTCClock`.

---

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [March 18, 2025, 7:09pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/11 "2025-03-18T19:09:58Z")

</div>

So the only other prior art other than epochs is perhaps something inspired by `Date`'s `referenceDate` - using modern Swift naming it might be instead called `reference` but that is a bit confusing to other terminology.

---

<div class="post-metadata">

**Author:** ![John\_McCall](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/john_mccall/32/1351_2.png) [@John\_McCall](https://forums.swift.org/u/John_McCall)\
**Post date:** [March 18, 2025, 7:35pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/12 "2025-03-18T19:35:00Z")

</div>

Would `systemEpoch` be clearer, if there really is a documentable assumption that this corresponds to some system-wide value and not just something internal to Swift?

---

<div class="post-metadata">

**Author:** ![grynspan](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/grynspan/32/15315_2.png) [@grynspan](https://forums.swift.org/u/grynspan)\
**Post date:** [March 18, 2025, 9:37pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/13 "2025-03-18T21:37:05Z")

</div>

I like that—it strongly implies the epoch is system-specific and not universal.

Bikeshedding:

- `currentEpoch`
- `bootEpoch`
- `localEpoch`
- `machineEpoch`
- `transientEpoch`

---

<div class="post-metadata">

**Author:** ![Philippe\_Hausler](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/philippe_hausler/32/22569_2.png) [@Philippe\_Hausler](https://forums.swift.org/u/Philippe_Hausler)\
**Post date:** [March 18, 2025, 10:44pm UTC](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017/14 "2025-03-18T22:44:39Z")

</div>

I'm ok with `systemEpoch` since that is also applicable to the UTCClock too.
