Add EventLoop.now API for getting the current time (#3015)

### Motivation

Code that tries to work with `NIODeadline` can be challenging to test
using `EmbeddedEventLoop` and `NIOAsyncTestingEventLoop` because they
have their own, fake clock.

These testing event loops do implement `scheduleTask(in:_)` to submit
work in the future, relative to the event loop clock, but there is no
way to get the event loop's current notion of "now", as a `NIODeadline`,
and users sometimes find that `NIODeadline.now`, which returns the time
of the real clock, to be surprising.

### Modifications

Add `EventLoop.now`  to get the current time of the event loop clock.

### Result

New APIs to support writing code that's easier to test.

Sources/NIOCore/EventLoop.swift

@@ -269,6 +269,9 @@ public protocol EventLoop: EventLoopGroup {
     @preconcurrency
     func submit<T>(_ task: @escaping @Sendable () throws -> T) -> EventLoopFuture<T>
 
+    /// The current time of the event loop.
+    var now: NIODeadline { get }
+
     /// Schedule a `task` that is executed by this `EventLoop` at the given time.
     ///
     /// - Parameters:
@@ -394,6 +397,11 @@ public protocol EventLoop: EventLoopGroup {
     func cancelScheduledCallback(_ scheduledCallback: NIOScheduledCallback)
 }
 
+extension EventLoop {
+    /// Default implementation of `now`: Returns `NIODeadline.now()`.
+    public var now: NIODeadline { .now() }
+}
+
 extension EventLoop {
     /// Default implementation of `makeSucceededVoidFuture`: Return a fresh future (which will allocate).
     public func makeSucceededVoidFuture() -> EventLoopFuture<Void> {

Sources/NIOEmbedded/AsyncTestingEventLoop.swift

@@ -63,7 +63,9 @@ public final class NIOAsyncTestingEventLoop: EventLoop, @unchecked Sendable {
     /// The current "time" for this event loop. This is an amount in nanoseconds.
     /// As we need to access this from any thread, we store this as an atomic.
     private let _now = ManagedAtomic<UInt64>(0)
-    internal var now: NIODeadline {
+
+    /// The current "time" for this event loop. This is an amount in nanoseconds.
+    public var now: NIODeadline {
         NIODeadline.uptimeNanoseconds(self._now.load(ordering: .relaxed))
     }
 

Sources/NIOEmbedded/Embedded.swift

@@ -94,8 +94,9 @@ extension EmbeddedScheduledTask: Comparable {
 ///     responsible for ensuring they never call into the `EmbeddedEventLoop` in an
 ///     unsynchronized fashion.
 public final class EmbeddedEventLoop: EventLoop, CustomStringConvertible {
+    private var _now: NIODeadline = .uptimeNanoseconds(0)
     /// The current "time" for this event loop. This is an amount in nanoseconds.
-    internal var _now: NIODeadline = .uptimeNanoseconds(0)
+    public var now: NIODeadline { _now }
 
     private enum State { case open, closing, closed }
     private var state: State = .open

Sources/NIOPosix/SelectableEventLoop.swift

@@ -298,6 +298,12 @@ internal final class SelectableEventLoop: EventLoop {
         thread.isCurrent
     }
 
+    /// - see: `EventLoop.now`
+    @usableFromInline
+    internal var now: NIODeadline {
+        .now()
+    }
+
     /// - see: `EventLoop.scheduleTask(deadline:_:)`
     @inlinable
     internal func scheduleTask<T>(deadline: NIODeadline, _ task: @escaping () throws -> T) -> Scheduled<T> {

Tests/NIOEmbeddedTests/AsyncTestingEventLoopTests.swift

@@ -619,4 +619,14 @@ final class NIOAsyncTestingEventLoopTests: XCTestCase {
         await eventLoop.advanceTime(by: .seconds(1))
         XCTAssertEqual(counter.load(ordering: .relaxed), 3)
     }
+
+    func testCurrentTime() async {
+        let eventLoop = NIOAsyncTestingEventLoop()
+
+        await eventLoop.advanceTime(to: .uptimeNanoseconds(42))
+        XCTAssertEqual(eventLoop.now, .uptimeNanoseconds(42))
+
+        await eventLoop.advanceTime(by: .nanoseconds(42))
+        XCTAssertEqual(eventLoop.now, .uptimeNanoseconds(84))
+    }
 }

Tests/NIOEmbeddedTests/EmbeddedEventLoopTest.swift

@@ -396,7 +396,7 @@ public final class EmbeddedEventLoopTest: XCTestCase {
                 try eventLoop.syncShutdownGracefully()
                 childTasks.append(
                     scheduleRecursiveTask(
-                        at: eventLoop._now + childTaskStartDelay,
+                        at: eventLoop.now + childTaskStartDelay,
                         andChildTaskAfter: childTaskStartDelay
                     )
                 )
@@ -497,4 +497,35 @@ public final class EmbeddedEventLoopTest: XCTestCase {
         eventLoop.advanceTime(by: .seconds(1))
         XCTAssertEqual(counter, 3)
     }
+
+    func testCurrentTime() {
+        let eventLoop = EmbeddedEventLoop()
+
+        eventLoop.advanceTime(to: .uptimeNanoseconds(42))
+        XCTAssertEqual(eventLoop.now, .uptimeNanoseconds(42))
+
+        eventLoop.advanceTime(by: .nanoseconds(42))
+        XCTAssertEqual(eventLoop.now, .uptimeNanoseconds(84))
+    }
+
+    func testScheduleRepeatedTask() {
+        let eventLoop = EmbeddedEventLoop()
+
+        var counter = 0
+        eventLoop.scheduleRepeatedTask(initialDelay: .seconds(1), delay: .seconds(1)) { repeatedTask in
+            guard counter < 10 else {
+                repeatedTask.cancel()
+                return
+            }
+            counter += 1
+        }
+
+        XCTAssertEqual(counter, 0)
+
+        eventLoop.advanceTime(by: .seconds(1))
+        XCTAssertEqual(counter, 1)
+
+        eventLoop.advanceTime(by: .seconds(9))
+        XCTAssertEqual(counter, 10)
+    }
 }

Tests/NIOPosixTests/EventLoopTest.swift

@@ -1962,6 +1962,10 @@ private class EventLoopWithPreSucceededFuture: EventLoop {
         preconditionFailure("not implemented")
     }
 
+    var now: NIODeadline {
+        preconditionFailure("not implemented")
+    }
+
     @discardableResult
     func scheduleTask<T>(deadline: NIODeadline, _ task: @escaping () throws -> T) -> Scheduled<T> {
         preconditionFailure("not implemented")
@@ -2013,6 +2017,10 @@ private class EventLoopWithoutPreSucceededFuture: EventLoop {
         preconditionFailure("not implemented")
     }
 
+    var now: NIODeadline {
+        preconditionFailure("not implemented")
+    }
+
     @discardableResult
     func scheduleTask<T>(deadline: NIODeadline, _ task: @escaping () throws -> T) -> Scheduled<T> {
         preconditionFailure("not implemented")