Rework the conversions into a active clock accessor and add clock ids

Author: phausler

proposals/0526-deadline.md

@@ -139,7 +139,7 @@ The fundamental entry point for working with deadlines is a single function: `wi
 /// - Returns: The result of the operation if it completes successfully before or after the deadline expires.
 ///
 /// - Throws: The error thrown by the operation
-nonisolated(nonsending) public func withDeadline<Return: ~Copyable, Failure: Error, C: Clock>(
+nonisolated(nonsending) public func withDeadline<Return: ~Copyable, Failure: Error, C: Clock & Identifiable>(
   _ expiration: C.Instant,
   tolerance: C.Instant.Duration? = nil,
   clock: C = ContinuousClock(),
@@ -206,7 +206,7 @@ Constructing an instant every time is not per se the most terse; so a simple ext
 with the same compositional advantage as the primary entry point.
 
 ```swift
-nonisolated(nonsending) public func withDeadline<Return: ~Copyable, Failure: Error, C: Clock>(
+nonisolated(nonsending) public func withDeadline<Return: ~Copyable, Failure: Error, C: Clock & Identifiable>(
   in timeout: C.Instant.Duration,
   tolerance: C.Instant.Duration? = nil,
   clock: C = ContinuousClock(),
@@ -358,71 +358,92 @@ This error is propagated from whenever the task (or child task) is cancelled via
 The reason specified will then be available to the `CancellationError` and can be retrieved from the `reason`
 property on the cancellation error.
 
-#### Current deadlines and Clock
+#### Accessing active deadlines
 
-The deadline cannot be expressed as an existential since that would not be easily usable. So
-to access the current applied deadline a common accessor would need to be used.
-This most generally can be expressed as an earliest ContinuousClock instant representing 
-the deadline. This will also resolve a long standing pain point for clocks for the conversion
-between reasonable time-bases.
-
-To accomplish this a new required method will be added to the `Clock` protocol and 
-a default implementation will then also be provided such that existing implementations
-wont break but will have a sensible default that can be customized to something more 
-appropriate.
+External systems may need to interoperate with active deadlines. This means that the
+applied deadline needs to be retrievable, however this particularly becomes
+tricky since the clock is generic for the deadlines. To that end
+the accessor for the active deadline is generic for a clock type
 
 ```swift
-public protocol Clock<Duration>: Sendable {
-  associatedtype Duration
-  associatedtype Instant: InstantProtocol where Instant.Duration == Duration
-
-  var now: Instant { get }
-  var minimumResolution: Instant.Duration { get }
-
-  func sleep(until deadline: Instant, tolerance: Instant.Duration?) async throws
+extension Task where Success == Never, Failure == Never {
+  public static var hasActiveDeadline: Bool { get }
 
-  // New addition:
-  func earliestContinuousInstant(from instant: Instant) -> ContinousClock.Instant
+  public static func activeDeadline<C: Clock & Identifiable>(for clock: C) -> C.Instant?
 }
+```
 
-extension Clock {
-  public func earliestContinuousInstant(from instant: Instant) -> ContinuousClock.Instant { .now }
-}
+If any deadline is active then the static property `hasActiveDeadline` returns true.  
+This only applies to the current task if the execution of that task is within a call
+to `withDeadline`. This allows for determining the return of the `deadline` static
+function to be used to know if a known clock has a value being applied as a current
+deadline. This does mean that the usage must be aware of the potential clocks being 
+used. This is however a requirement since to use the deadline itself the clock must 
+be known for any sort of usage to an external system.
 
-extension ContinuousClock {
-  public func earliestContinuousInstant(from instant: Instant) -> ContinuousClock.Instant { instant }
-}
 
-extension SuspendingClock {
-  public func earliestContinuousInstant(from instant: Instant) -> ContinuousClock.Instant { 
-    let delta = instant - .now
-    return ContinousClock.now + delta
+```swift
+if Task.hasActiveDeadline {
+  if let deadline = Task.activeDeadline(for: ContinuousClock()) {
+    // use the deadline as a ContinuousClock.Instant
+  }
+  if let deadline = Task.activeDeadline(for: SuspendingClock()) {
+    // use the deadline as a SuspendingClock.Instant
   }
 }
 ```
 
-This will mean that ContinousClock and SuspendingClock will gain new implementations
-of this which will then return the earliest instant represented in reference to the 
-continuous clock.
-
-This all then means that the deadline APIs can use that implementation to vend
-out a earliest continuous deadline, alleviating the issues around existential `InstantProtocol`
-types and providing a reasonable frame of reference for expiration.
+When the call to `activeDeadline(for:)` is made, the query looks up the most narrow
+application of any specified deadline with that clock, if the current nesting of 
+`withDeadline` calls does not used the specified clock type then the next nesting
+up the call stack is used.
+
+If the nesting of `withDeadline` is stacked with a `ContinuousClock` deadline of 
+"in two seconds" and then a `SuspendingClock` of "in three seconds" and a new
+nesting is made of a `ContinuousClock` is made for "in 10 seconds" the last
+10 seconds is known to be less narrow than the outer 2 seconds continuous clock 
+deadline. This means that within the scope of the "in 10 seconds" deadline the query
+for the `activeDeadline(for: ContinuousClock.self)` would return the deadline of within 
+2 seconds and the `activeDeadline(for: SuspendingClock.self)` would return the deadline
+of within 3 seconds. Since clock instants cannot be compared without potentially
+arbitrarily lossy conversions it means that the query for the current applied deadline
+is only accurate to the specific clock type given. 
+
+#### Identification of Clocks for coalescing 
+
+The expected behavior when setting a deadline is that any active deadline, given a specific clock,
+will always apply with the most narrow deadline available. Specifically if a deadline is 
+active for an expiration of `in 10 seconds` and a new deadline is applied for `in 5 seconds` 
+relative both relative to the continuous clock, then the applied deadline within the new
+scope is the `in 5 seconds`. Likewise if the reverse was applied; where it is already at `in 5 seconds`
+and a new scope is applied to `in 10 seconds` both on the continuous clock, then the internal
+logic will effectively skip the `in 10 seconds` since that deadline is known to beyond the current
+active deadline. This must have some way of determining if a given clock passed in to 
+the `withDeadline` functions is that same specific clock. To that end, the clocks are 
+required to be identified. The two major clocks; `ContinuousClock` and `SuspendingClock`
+both will gain a new conformance to `Identifiable` and each of which will have a new ID
+type of `SystemClockID`. As a side effect this means that new APIs can be written as: 
+`where C: Clock & Identifiable, C.ID == SystemClockID`. That particular refinement not only
+allows for the direct identification of the specific clock but also a constraint to the 
+standard system clocks.
+
+Note: since the system clock may grow additional identifiers it is left as non-exhaustive.
 
 ```swift
-extension Task where Success == Never, Failure == Never {
-  public static var currentEarliestContinuousDeadline: ContinuousClock.Instant? { get }
+@nonexhaustive
+public enum SystemClockID: Hashable {
+  case continuous
+  case suspending
 }
-```
 
-This accessor does not preclude any potential more rich type information for deadlines
-and clocks being added later, but provides a straightforward interface for interoperation
-with external systems. The Task deadline can only be reasonable vended to the current task
-since that value would be only transient upon a given deadline - therefore accessing it 
-externally would be rather prone to race conditions. The per task lookup will traverse 
-the nested deadlines and calculate the earliest of all of the applied deadlines that would
-fire per the ContinuousClock. By doing so this leaves the least inaccuracy of measurement
-(and control by custom clocks as well) to translate to existing external systems.
+extension ContinuousClock: Identifiable {
+  public var id: SystemClockID { .continuous }
+}
+
+extension SuspendingClock: Identifiable {
+  public var id: SystemClockID { .suspending }
+}
+```
 
 ### Behavioral Details
 
@@ -795,6 +816,8 @@ nesting. This approach was not taken because:
    explicit `withDeadline` API would remain useful even if such a mechanism were added.
 
 ## Changelog
+- 1.2 Revisde for feedback
+  - Added accessors to add a way to access the active deadlines
 - 1.1 Returned for revision
   - The typed throws signature was altered to avoid an extra error type
   - Removed the restriction around the instant requiring the duration type to be `Swift.Duration`