Skip to content

Commit a89b64f

Browse files
authored
Assign SE-0473 to the clocks proposal and put it into review
Also some more assorted wording updates
1 parent 897d6d3 commit a89b64f

File tree

1 file changed

+6
-6
lines changed

1 file changed

+6
-6
lines changed

proposals/NNNN-clock-epochs.md renamed to proposals/0473-clock-epochs.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Clock Epochs
22

3-
* Proposal: [SE-NNNN](NNNN-clock-epochs.md)
3+
* Proposal: [SE-0473](0473-clock-epochs.md)
44
* Authors: [Philippe Hausler](https://github.com/phausler)
55
* Review Manager: [John McCall](https://github.com/rjmccall)
6-
* Status: **Awaiting implementation**
6+
* Status: **Active Review (March 28th...April 9th, 2025)**
77
* Implementation:
88
* Review: ([pitch](https://forums.swift.org/t/pitch-suspendingclock-and-continuousclock-epochs/78017))
99

@@ -15,11 +15,11 @@
1515

1616
The `Instant` type of a `Clock` represents a moment in time as measured by that clock. `Clock` intentionally imposes very few requirements on `Instant` because different kinds of clocks can have very different characteristics. Just because something does not belong on the generic `Clock` protocol, however, does not mean it shouldn't be exposed in the interface of a concrete clock type.
1717

18-
Many clocks have a concept of a reference instant, also called an "epoch", that has special meaning for the clock. For example, the Unix `gettimeofday` function measures the nominal elapsed time since 00:00 UTC on January 1st, 1970, an instant often called the "Unix epoch". Swift's `SuspendingClock` and `ContinuousClock` are defined using system facilities that similarly measure time relative to an epoch, and while the exact definition of the epoch is system-specific, it is at least consistent for any given system. This means that durations since the epoch can be meaningfully compared within the system, even with code in other processes or written in other languages (as long as it uses the same system facilities).
18+
Many clocks have a concept of a reference instant, also called an "epoch", that has special meaning for the clock. For example, the Unix `gettimeofday` function measures the nominal elapsed time since 00:00 UTC on January 1st, 1970, an instant often called the "Unix epoch". Swift's `SuspendingClock` and `ContinuousClock` are defined using system facilities that similarly measure time relative to an epoch, and while the exact definition of the epoch is system-specific, it is at least consistent for any given system. This means that durations since the epoch can be meaningfully compared within the system, even across multiple processes or with code written in other languages (as long as they use the same system facilities).
1919

2020
## Proposed solution
2121

22-
Two new properties will be added, one to `SuspendingClock` and another to `ContinuousClock`. These properties define the system epoch that all `Instant` types for the clock are derived from; practically speaking, this is the "zero" point for these clocks. Since the values may be relative to the particular system they are being used on, their names reflect that they are representative of the system's sense of an epoch and should not be expected to be meaningfully comparable (or serializable) across systems.
22+
Two new properties will be added, one to `SuspendingClock` and another to `ContinuousClock`. These properties define the system epoch that all `Instant` types for the clock are derived from; practically speaking, this is the "zero" point for these clocks. Since the values may be relative to the particular system they are being used on, their names reflect that they are a system-specific definition and should not be expected to be consistent (or meaningfully serializable) across systems.
2323

2424
## Detailed design
2525

@@ -33,7 +33,7 @@ extension SuspendingClock {
3333
}
3434
```
3535

36-
On both Darwin and Linux, the system epochs of these clocks is set at boot time, and so measurements relative to the epoch can used to gather information such as the uptime or active time of a system:
36+
On most platforms, including Apple platforms, Linux, and Windows, the system epoch of these clocks is set at boot time, and so measurements relative to the epoch can used to gather information such as the uptime or active time of a system:
3737

3838
```swift
3939
let clock = ContinousClock()
@@ -47,7 +47,7 @@ let clock = SuspendingClock()
4747
let activeTime = clock.now - clock.systemEpoch
4848
```
4949

50-
Swift will make an effort to maintain this property on other supported systems when possible. However, it cannot be guaranteed for all systems, such as when the concept of uptime either doesn't apply or is intentionally not exposed to the programming environment for privacy reasons.
50+
However, this cannot be guaranteed for all possible platforms. A platform may choose to use a different instant for its system epoch, perhaps because the concept of uptime doesn't apply cleanly on the platform or because it is intentionally not exposed to the programming environment for privacy reasons.
5151

5252
## ABI compatibility
5353

0 commit comments

Comments
 (0)