Skip to content

Update the proposal for UTCClock to reflect the discussion surrounding it #1445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

phausler
Copy link
Contributor

There were a few places where the examples left some lack of clarity of the proposed clock usages and behaviors. This refines those examples to a more concrete use case that avoids any confusion about the role associated with UTCClock and additionally clarifies the stance on the placement/homing of Date, the definition of timezones and the relationship to UTC, the naming of systemEpoch and finally a reflection of the proposal discussion out lasting the cutoff of 6.2.

@phausler phausler requested a review from itingliu July 17, 2025 23:43
itingliu
itingliu previously approved these changes Jul 22, 2025

The structure of the `UTCClock` is trivially sendable since it houses no specific state and has the defined typealias of its `Instant` as `Date`. The minimum feasible resolution of `Date` is 1 nanosecond (however that may vary from platform to platform where Foundation is implemented).
The structure of the `UTCClock` is trivially sendable since it houses no specific state and has the defined typealias of its `Instant` as `Date`. The minimum feasible resolution of `Date` is 1 nanosecond. The sleep method may respond to host system time adjustments; e.g. if a system has it's time changed manually or if the system adjusts the time drift via ntp updates so the sleep method, unlike ContinuousClock, is not strictly monotonic. However, since UTC itself is the root definition of timezones[^timezones] there is no daylight savings time adjustment; any calculation for accounting to DST must be done before hand by interacting with the Calendar and deriving a Date accordingly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The structure of the `UTCClock` is trivially sendable since it houses no specific state and has the defined typealias of its `Instant` as `Date`. The minimum feasible resolution of `Date` is 1 nanosecond. The sleep method may respond to host system time adjustments; e.g. if a system has it's time changed manually or if the system adjusts the time drift via ntp updates so the sleep method, unlike ContinuousClock, is not strictly monotonic. However, since UTC itself is the root definition of timezones[^timezones] there is no daylight savings time adjustment; any calculation for accounting to DST must be done before hand by interacting with the Calendar and deriving a Date accordingly.
The structure of the `UTCClock` is trivially sendable since it houses no specific state and has the defined typealias of its `Instant` as `Date`. The minimum feasible resolution of `Date` is 1 nanosecond. The sleep method may respond to host system time adjustments; e.g. if a system has its time changed manually or if the system adjusts the time drift via ntp updates so the sleep method, unlike ContinuousClock, is not strictly monotonic. However, since UTC itself is the root definition of timezones[^timezones] there is no daylight savings time adjustment; any calculation for accounting to DST must be done before hand by interacting with the Calendar and deriving a Date accordingly.

@@ -64,13 +64,13 @@ extension UTCClock: Clock {
The extension of `Date` conforms it to `InstantProtocol` and adds one addition "near miss" of the protocol as an additional function that in practice feels like a default parameter. This `duration(to:includingLeapSeconds:)` function provides the calculation of the duration from one point in time to another and calculates if the span between the two points includes a leap second or not. This calculation can be used for historical astronomical data since the irregularity of the rotation causes variation in the observed solar time. Those points are historically fixed and are a known series of events at specific dates (in UTC)[^utclist].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this part an outdated version of the previous? I don't see a duration(to:includingLeapSeconds:). Should it just be func duration(to other: Date)?

And the functionality to get the leap seconds between two would be covered by public static func leapSeconds(from start: Date, to end: Date) -> Duration below


It was considered to add a new `Instant` type instead of depending on `Date` however this was rejected since it would mean re-implementing a vast swath of the supporting APIs for `Calendar` and such. The advantage of this is minimal and does not counteract the additional API complexity.
It was considered to add a new `Instant` type instead of depending on `Date` however this was rejected since it would mean re-implementing a vast swath of the supporting APIs for `Calendar` and such. The advantage of this is minimal and does not counteract the additional API complexity. This consideration did delve into the idea of moving Date to a lower scope and also changing it's storage, however due to the complexity of that; it is considered a non-goal of this proposal and squarely in the out of scope territory. The beneifit of scheduling and appropriate calculations with regards to leap seconds are valueable on their own and distinctly seperable tasks to any sort of re-orgnaization of Date et al.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo:

Suggested change
It was considered to add a new `Instant` type instead of depending on `Date` however this was rejected since it would mean re-implementing a vast swath of the supporting APIs for `Calendar` and such. The advantage of this is minimal and does not counteract the additional API complexity. This consideration did delve into the idea of moving Date to a lower scope and also changing it's storage, however due to the complexity of that; it is considered a non-goal of this proposal and squarely in the out of scope territory. The beneifit of scheduling and appropriate calculations with regards to leap seconds are valueable on their own and distinctly seperable tasks to any sort of re-orgnaization of Date et al.
It was considered to add a new `Instant` type instead of depending on `Date` however this was rejected since it would mean re-implementing a vast swath of the supporting APIs for `Calendar` and such. The advantage of this is minimal and does not counteract the additional API complexity. This consideration did delve into the idea of moving Date to a lower scope and also changing its storage, however due to the complexity of that; it is considered a non-goal of this proposal and squarely in the out of scope territory. The benefit of scheduling and appropriate calculations with regards to leap seconds are valuable on their own and distinctly separable tasks to any sort of re-organization of Date et al.

@itingliu itingliu dismissed their stale review July 22, 2025 00:16

hit the approval by mistake. There are a few nits

@itingliu
Copy link
Contributor

@swift-ci please test

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants