v5.0.0 - dispatchTime on all Callbacks

- Added `dispatchTime: DispatchTime` on all Callbacks, and providing this value on all Callback invocations.
- Version will bump up to 5.0.0 to reflect this interface-breaking change
- README.md updated to reflect new changes

Author: LK-Simon

README.md

@@ -130,7 +130,7 @@ let package = Package(
     dependencies: [
         .package(
             url: "https://github.com/Flowduino/EventDrivenSwift.git",
-            .upToNextMajor(from: "4.2.0")
+            .upToNextMajor(from: "5.0.0")
         ),
     ],
     //...
@@ -217,7 +217,7 @@ class TemperatureProcessor: EventThread {
     }
 
     /// Define our Callback Function to process received TemperatureEvent Events
-    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
 
     }
 }
@@ -230,6 +230,8 @@ The function `registerEventListeners` will be called automatically when an insta
 
 Our *Callback* (or *Handler* or *Listener Event*) is called `onTemperatureEvent`, which is where we will implement whatever *Operation* is to be performed against a `TemperatureEvent`.
 
+Version 5.0.0 introduces the new parameter, `dispatchTime`, which will always provide the `DispatchTime` reference at which the *Event* was *Dispatched*. You can use this to determine *Delta* (how much time has passed since the *Event* was *Dispatched*), which is particularly useful if you are performing interpolation and/or extrapolation.
+
 Now, let's actually do something with our `TemperatureEvent` in the `onTemperatureEvent` method.
 ```swift
     /// An Enum to map a Temperature value onto a Rating
@@ -262,7 +264,7 @@ Now, let's actually do something with our `TemperatureEvent` in the `onTemperatu
     @ThreadSafeSemaphore public var temperatureInCelsius: Float = Float.zero
     @ThreadSafeSemaphore public var temperatureRating: TemperatureRating = .freezing
 
-    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
     }
@@ -315,7 +317,7 @@ protocol TemperatureProcessorObserver: AnyObject {
 ```
 Now let's modify the `onTemperatureEvent` method we implemented in the previous example:
 ```swift
-    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
 
@@ -343,7 +345,7 @@ enum TemperatureRatingEvent: Eventable {
 ```
 With the *Event* type defined, we can now once more expand our `onTemperatureEvent` to *Dispatch* our reciprocal `TemperatureRatingEvent`:
 ```swift
-    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority) {
+    func onTemperatureEvent(_ event: TemperatureEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = TemperatureRating.fromTemperature(event.temperatureInCelsius)
 
@@ -385,7 +387,7 @@ class TemperatureRatingViewModel: ObservableObject {
 
     var listenerHandle: EventListenerHandling?
 
-    internal func onTemperatureRatingEvent(_ event: TemperatureRatingEvent, _ priority: EventPriority) {
+    internal func onTemperatureRatingEvent(_ event: TemperatureRatingEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = event.temperatureRating
     }
@@ -438,7 +440,7 @@ class TemperatureRatingViewModel: ObservableObject {
 
     var listenerHandle: EventListenerHandling?
 
-    internal func onTemperatureRatingEvent(_ event: TemperatureRatingEvent, _ priority: EventPriority) {
+    internal func onTemperatureRatingEvent(_ event: TemperatureRatingEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) {
         temperatureInCelsius = event.temperatureInCelsius
         temperatureRating = event.temperatureRating
     }
@@ -480,9 +482,8 @@ The above example would use the `EventPoolLowestLoadBalancer` implementation, wh
 ## Features Coming Soon
 `EventDrivenSwift` is an evolving and ever-improving Library, so here are lists of the features you can expect in future releases.
 
-Version 4.3.0 (or 5.0.0 if interface-breaking changes are required):
-- **Event Pool Scalers** - Dynamic Scaling for `EventPool` instances will be fully-implemented
-- **Latest-Only Events** - A Dispatch option to replace any unprocessed (older) *Events* with the newest *Event* of that specific *Eventable* type. This will be useful for things like sensor readings, where you only care about the most recent value possible (because older values are no longer relevant)
+Version 5.1.0 (or 6.0.0 if interface-breaking changes are required):
+- **Event Pool Scalers** - Dynamic Scaling for `EventPool` instances will be fully-implemented (for the moment, no automatic Scaling will occur, and you cannot change the scale of an *Event Pool* once it has been initialised)
 
 ## License
 

Sources/EventDrivenSwift/Event/Wrappers/EventListeners.swift

@@ -7,7 +7,7 @@
 //
 
 import Foundation
-
+/*
 public protocol EventListenerCallbackContainer {
     associatedtype TEventType: Eventable
 
@@ -35,3 +35,4 @@ public struct EventListeners<TOwner: AnyObject> {
         return results
     }
 }
+*/

Sources/EventDrivenSwift/Event/Wrappers/EventMethod.swift

@@ -8,7 +8,7 @@
 
 import Foundation
 
-public typealias EventMethodTypedEventCallback<TOwner: AnyObject, TEvent: Any> = (_ sender: TOwner, _ event: TEvent, _ priority: EventPriority) -> ()
+public typealias EventMethodTypedEventCallback<TOwner: AnyObject, TEvent: Any> = (_ sender: TOwner, _ event: TEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) -> ()
 
 /**
  Any Property wrapped with `EventMethod` will automatically conform to `EventMethodContainer`
@@ -28,7 +28,7 @@ public protocol EventMethodContainer {
 /**
  Decorate Typed Event Callback Closures as `var` with `@EventMethod<TEventType>` to automatically register them.
  - Author: Simon J. Stuart
- - Version: 4.1.0
+ - Version: 5.0.0
  */
 @propertyWrapper
 public struct EventMethod<TOwner: AnyObject, TEventType: Eventable>: EventMethodContainer {
@@ -37,9 +37,9 @@ public struct EventMethod<TOwner: AnyObject, TEventType: Eventable>: EventMethod
 
     private weak var owner: AnyObject? = nil
 
-    private func callback(event: TEventType, priority: EventPriority) {
+    private func callback(event: TEventType, priority: EventPriority, dispatchTime: DispatchTime) {
         if let typedOwner = owner as? TOwner {
-            wrappedValue?(typedOwner, event, priority)
+            wrappedValue?(typedOwner, event, priority, dispatchTime)
         }
     }
 

Sources/EventDrivenSwift/EventListener/EventListenable.swift

@@ -13,14 +13,14 @@ import Foundation
  - Author: Simon J. Stuart
  - Version: 3.0.0
  */
-public typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority) -> ()
+public typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority, _ dispatchTime: DispatchTime) -> ()
 
 /**
  Convienience `typealias` used for Typed Event Callbacks
  - Author: Simon J. Stuart
  - Version: 3.0.0
  */
-public typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority) -> ()
+public typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) -> ()
 
 public enum ExecuteEventOn {
     /**

Sources/EventDrivenSwift/EventListener/EventListener.swift

@@ -73,23 +73,23 @@ open class EventListener: EventHandler, EventListenable {
                 Task { // We raise a Task because we don't want the entire Listener blocked in the event the dispatchQueue is busy or blocked!
                     let dispatchQueue = listener.dispatchQueue ?? DispatchQueue.main
                     dispatchQueue.async {
-                        listener.callback(event.event, priority)
+                        listener.callback(event.event, priority, event.dispatchTime)
                     }
                 }
             case .listenerThread:
-                listener.callback(event.event, priority)
+                listener.callback(event.event, priority, event.dispatchTime)
             case .taskThread:
                 Task {
-                    listener.callback(event.event, priority)
+                    listener.callback(event.event, priority, event.dispatchTime)
                 }
             }
         }
     }
 
     @discardableResult public func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn = .requesterThread, interestedIn: EventListenerInterest = .all) -> EventListenerHandling {
         let eventTypeName = forEventType.getEventTypeName()
-        let method: EventCallback = { event, priority in
-            self.callTypedEventCallback(callback, forEvent: event, priority: priority)
+        let method: EventCallback = { event, priority, dispatchTime in
+            self.callTypedEventCallback(callback, forEvent: event, priority: priority, dispatchTime: dispatchTime)
         }
         let eventListenerContainer = EventListenerContainer(requester: requester, callback: method, dispatchQueue: OperationQueue.current?.underlyingQueue, executeOn: executeOn, interestedIn: interestedIn)
         _eventListeners.withLock { eventCallbacks in
@@ -157,9 +157,9 @@ open class EventListener: EventHandler, EventListenable {
         - forEvent: The instance of the `Eventable` type to be processed
         - priority: The `EventPriority` with which the `forEvent` was dispatched
      */
-    internal func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority) {
+    internal func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority, dispatchTime: DispatchTime) {
         if let typedEvent = forEvent as? TEvent {
-            callback(typedEvent, priority)
+            callback(typedEvent, priority, dispatchTime)
         }
     }
 }

Sources/EventDrivenSwift/EventThread/EventThread.swift

@@ -32,7 +32,7 @@ public protocol ThreadEventMethodContainer {
  - Note: Inherit from this to implement a discrete unit of code designed specifically to operate upon specific `Eventable` types containing information useful to its operation(s)
  */
 open class EventThread: EventReceiver, EventThreadable {
-    public typealias EventMethodTypedEventCallback<TOwner: EventThread, TEvent: Any> = (_ sender: TOwner, _ event: TEvent, _ priority: EventPriority) -> ()
+    public typealias EventMethodTypedEventCallback<TOwner: EventThread, TEvent: Any> = (_ sender: TOwner, _ event: TEvent, _ priority: EventPriority, _ dispatchTime: DispatchTime) -> ()
 
     /**
      Property Wrapper to simplify the registration of Event Callbacks in `EventThread`-inheriting types.
@@ -54,9 +54,9 @@ open class EventThread: EventReceiver, EventThreadable {
 
         private weak var owner: AnyObject? = nil
 
-        @inline(__always) private func callback(event: TEventType, priority: EventPriority) {
+        @inline(__always) private func callback(event: TEventType, priority: EventPriority, dispatchTime: DispatchTime) {
             if let typedOwner = owner as? TOwner {
-                wrappedValue?(typedOwner, event, priority)
+                wrappedValue?(typedOwner, event, priority, dispatchTime)
             }
         }
 
@@ -139,7 +139,7 @@ open class EventThread: EventReceiver, EventThreadable {
         if callbackContainer == nil { return } // If there is no Callback, we will just return!
 
         for callback in callbackContainer! {
-            callback.callback(event.event, priority)
+            callback.callback(event.event, priority, event.dispatchTime)
         }
     }
 
@@ -163,8 +163,8 @@ open class EventThread: EventReceiver, EventThreadable {
                 bucket = [EventCallbackContainer]()
             }
 
-            callbackContainer = EventCallbackContainer(callback: { event, priority in
-                self.callTypedEventCallback(callback, forEvent: event, priority: priority)
+            callbackContainer = EventCallbackContainer(callback: { event, priority, dispatchTime in
+                self.callTypedEventCallback(callback, forEvent: event, priority: priority, dispatchTime: dispatchTime)
             }, eventType: forEventType)
 
             bucket!.append(callbackContainer!)
@@ -192,9 +192,9 @@ open class EventThread: EventReceiver, EventThreadable {
         - forEvent: The instance of the `Eventable` type to be processed
         - priority: The `EventPriority` with which the `forEvent` was dispatched
      */
-    @inline(__always) open func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority) {
+    @inline(__always) open func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority, dispatchTime: DispatchTime) {
         if let typedEvent = forEvent as? TEvent {
-            callback(typedEvent, priority)
+            callback(typedEvent, priority, dispatchTime)
         }
     }
 

Sources/EventDrivenSwift/UIEventThread/UIEventThread.swift

@@ -25,10 +25,10 @@ open class UIEventThread: EventThread, UIEventThreadable {
         }
     }
 
-    override open func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority) {
+    override open func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority, dispatchTime: DispatchTime) {
         Task { /// Have to use a Task because this method is not `async`
             await MainActor.run { /// Forces the call to be invoked on the `MainActor` (UI Thread)
-                super.callTypedEventCallback(callback, forEvent: forEvent, priority:  priority)
+                super.callTypedEventCallback(callback, forEvent: forEvent, priority: priority, dispatchTime: dispatchTime)
             }
         }
     }

Tests/EventDrivenSwiftTests/BasicEventListenerTests.swift

@@ -18,15 +18,15 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
         var bar: String
     }
 
-    @EventMethod<BasicEventListenerTests, TestEventTypeOne>(executeOn: .taskThread) var event1 = { (self, event: TestEventTypeOne, priority: EventPriority) in
+    @EventMethod<BasicEventListenerTests, TestEventTypeOne>(executeOn: .taskThread) var event1 = { (self, event: TestEventTypeOne, priority: EventPriority, dispatchTime: DispatchTime)  in
         self.doTestEvent(event: event, priority: priority)
     }
 
     func doTestEvent(event: TestEventTypeOne, priority: EventPriority) {
         print("onTestEvent: foo = \(event.foo)")
     }
 
-    @EventMethod<BasicEventListenerTests, TestEventTypeTwo>(executeOn: .taskThread) var event2 = { (self, event: TestEventTypeTwo, priority: EventPriority) in
+    @EventMethod<BasicEventListenerTests, TestEventTypeTwo>(executeOn: .taskThread) var event2 = { (self, event: TestEventTypeTwo, priority: EventPriority, dispatchTime: DispatchTime) in
         self.doTestEventTwo(event: event, priority: priority)
     }
 
@@ -43,7 +43,7 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
         registerListeners()
         XCTAssertEqual(myFoo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(myFoo)")
 
-        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
+        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority, dispatchTime) in
             self.myFoo = event.foo
             self.awaiter.signal()
         }, executeOn: .listenerThread)
@@ -63,7 +63,7 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
 //        registerListeners()
         XCTAssertEqual(myFoo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(myFoo)")
 
-        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
+        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority, dispatchTime) in
             self.myFoo = event.foo
             self.awaiter.signal()
         }, executeOn: .taskThread)

Tests/EventDrivenSwiftTests/BasicEventPoolTests.swift

@@ -31,7 +31,7 @@ final class BasicEventPoolTests: XCTestCase {
     class PoolTestingThread: EventThread {
         override func registerEventListeners() {
             addEventCallback(
-                { (event: PoolTestingEvent, priority) in
+                { (event: PoolTestingEvent, priority, dispatchTime) in
                     Thread.sleep(forTimeInterval: 5)
                     PoolTestStatic.setValue(index: event.index, value: event.value)
                     Thread.sleep(forTimeInterval: 5)

Tests/EventDrivenSwiftTests/BasicEventSchedulingTests.swift

@@ -19,7 +19,7 @@ final class BasicEventSchedulingTests: XCTestCase {
     private var executed: DispatchTime? = nil
 
     func testPerformanceExample() throws {
-        TestEvent.addListener(self, { (event: TestEvent, priority) in
+        TestEvent.addListener(self, { (event: TestEvent, priority, dispatchTime) in
             print("TestEvent where foo = \(event.foo)")
             self.testValue = event.foo
             self.executed = DispatchTime.now()