EventListener completed

- `EventListener` implementation completed
- `EventCentral` updated to provide a centralised `EventListener` for global use
- `Eventable` introduces two new methods:
  - `addListener` registers an arbitrary Listener against the referenced `Eventable` Type and returns a `UUID` token for that Listener
  - `removeListener` unregisters the Listener specified by its `UUID` token

Author: LK-Simon

README.md

@@ -125,7 +125,7 @@ let package = Package(
     dependencies: [
         .package(
             url: "https://github.com/Flowduino/EventDrivenSwift.git",
-            .upToNextMajor(from: "2.0.0")
+            .upToNextMajor(from: "3.0.0")
         ),
     ],
     //...
@@ -346,13 +346,59 @@ As you can see, we can create and *Dispatch* an *Event* in a single operation. T
 Now that we've walked through these basic Usage Examples, see if you can produce your own `EventReceiver` to process `TemperatureRatingEvent`s. Everything you need to achieve this has already been demonstrated in this document.
 
 ## `UIEventReceiver`
-Version 2.0.0 introduces the `UIEventReceiver` base class, which operates exactly the same way as `EventReciever`, with the notable difference being that your registered *Event* Callbacks will **always** be invoked on the `MainActor` (or "UI Thread"). You can simply inherit from `UIEventReceiver` instead of `EventReceiver` whenever it is imperative for one or more *Event* Callbacks to execute on the `MainActor`.
+Version 2.0.0 introduced the `UIEventReceiver` base class, which operates exactly the same way as `EventReciever`, with the notable difference being that your registered *Event* Callbacks will **always** be invoked on the `MainActor` (or "UI Thread"). You can simply inherit from `UIEventReceiver` instead of `EventReceiver` whenever it is imperative for one or more *Event* Callbacks to execute on the `MainActor`.
+
+## `EventListener`
+Version 3.0.0 introduced the `EventListener` concept to the Library.
+
+An `EventListener` is a universal way of subscribing to *Events*, anywhere in your code!
+
+By design, `EventDrivenSwift` provides a *Central Event Listener*, which is automatically initialized should any of your code register a *Listener* for an *Event* by reference to the `Eventable` type.
+
+**Important Note:** `EventListener` will always invoke the associated `Callbacks` on the same Thread (or `DispatchQueue`) from whence the *Listener* registered! This is an extremely useful behaviour, because it means that *Listeners* registered from the `MainActor` (or "UI Thread") will always execute on that Thread, with no additional overhead or code required by you.
+
+Let's register a simple *Listener* in some arbitrary `class`. For this example, let's produce a hypothetical *View Model* that will *Listen* for `TemperatureRatingEvent`, and would invalidate an owning `View` to show the newly-received values.
+
+For the sake of this example, let's define this the pure SwiftUI way, *without* taking advantage of our `Observable` library: 
+```swift
+class TemperatureRatingViewModel: ObservableObject {
+    @Published var temperatureInCelsius: Float
+    @Published var temperatureRating: TemperatureRating
+    
+    var listenerToken: UUID
+    
+    internal func onTemperatureRatingEvent(_ event: TemperatureRatingEvent, _ priority: EventPriority) {
+        temperatureInCelsius = event.temperatureInCelsius
+        temperatureRating = event.temperatureRating
+    }
+    
+    init() {
+        // Let's register our Event Listener Callback!
+        listenerToken = TemperatureRatingEvent.addListener(self, onTemperatureRatingEvent)
+    }
+}
+```
+It really is **that** simple!
+
+We can use a direct reference to an `Eventable` type, and invoke the `addListener` method, automatically bound to all `Eventable` types, to register our *Listener*.
+
+In the above example, whenever the *Reciprocal Event* named `TemperatureRatingEvent` is dispatched, the `onTemperatureRatingEvent` method of any `TemperatureRatingViewModel` instance(s) will be invoked, in the context of that *Event*!
+
+Don't worry about managing the lifetime of your *Listener*! If the object which owns the *Listener* is destroyed, the *Listener* will be automatically unregistered for you!
+
+Another thing to note about the above example is the `listenerToken`. Whenever you register a *Listener*, it will return a Unique Universal ID (a `UUID`) value. You can use this value to *Unregister* your *Listener* at any time:
+```swift
+    TemperatureRatingEvent.removeListener(listenerToken)
+```
+This way, when an *Event* is no longer relevant to your code, you can simply call `removeListener` against the `Eventable` type, and pass in the token returned when you added the *Listener* in the first place.
+
+`EventListener`s are an extremely versatile and very powerful addition to `EventDrivenSwift`.
 
 ## Features Coming Soon
 `EventDrivenSwift` is an evolving and ever-improving Library, so here is a list of the features you can expect in future releases:
 - **Event Pools** - A superset expanding upon a given `EventReceiver` descendant type to provide pooled processing based on given scaling rules and conditions.
 
-These are the features intended for the next Release, which will either be *2.1.0* or *3.0.0* depending on whether these additions require interface-breaking changes to the interfaces in version *2.0.0*.
+These are the features intended for the next Release, which will either be *3.1.0* or *4.0.0* depending on whether these additions require interface-breaking changes to the interfaces in version *3.0.0*.
 
 ## License
 

Sources/EventDrivenSwift/Central/EventCentral.swift

@@ -66,9 +66,15 @@ final public class EventCentral: EventDispatcher, EventCentralable {
         }
     }
 
-    internal var eventListener = EventListener()
+    private var _eventListener: EventListenable?
+    internal var eventListener: EventListenable {
+        get {
+            if _eventListener == nil { _eventListener = EventListener() }
+            return _eventListener!
+        }
+    }
 
-    @inline(__always) public static func addListener<TEvent>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID where TEvent : Eventable {
+    @discardableResult @inline(__always) public static func addListener<TEvent>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID where TEvent : Eventable {
         return _shared.eventListener.addListener(requester, callback, forEventType: forEventType)
     }
 

Sources/EventDrivenSwift/Central/EventCentralable.swift

@@ -68,7 +68,7 @@ public protocol EventCentralable {
         - forEventType: The `Eventable` Type for which to Register  the Callback
      - Returns: A `UUID` value representing the `token` associated with this Event Callback
      */
-    static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
 
     /**
      Locates and removes the given Listener `token` (if it exists) from the Central Event Listener

Sources/EventDrivenSwift/Event/Eventable.swift

@@ -33,6 +33,26 @@ public protocol Eventable {
         - priority: The Priority with which to process this Event
      */
     func stack(priority: EventPriority)
+    
+    /**
+     Registers an Event Listner Callback for the given `Eventable` Type with the Central Event Listener
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - requester: The Object owning the Callback Method
+        - callback: The code to invoke for the given `Eventable` Type
+     - Returns: A `UUID` value representing the `token` associated with this Event Callback
+     */
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>) -> UUID
+    
+    /**
+     Locates and removes the given Listener `token` (if it exists) from the Central Event Listener
+     - Author: Simon J. Stuart
+     - Version: 3.0.0
+     - Parameters:
+        - token: The Token of the Listener you wish to remove
+     */
+    static func removeListener(_ token: UUID)
 }
 
 /**
@@ -53,10 +73,18 @@ extension Eventable {
  */
 extension Eventable {
     public func queue(priority: EventPriority = .normal) {
-        EventCentral.shared.queueEvent(self, priority: priority)
+        EventCentral.queueEvent(self, priority: priority)
     }
 
     public func stack(priority: EventPriority = .normal) {
-        EventCentral.shared.stackEvent(self, priority: priority)
+        EventCentral.stackEvent(self, priority: priority)
+    }
+    
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>) -> UUID {
+        return EventCentral.addListener(requester, callback, forEventType: Self.self)
+    }
+    
+    static func removeListener(_ token: UUID) {
+        EventCentral.removeListener(token, typeOf: Self.self)
     }
 }

Sources/EventDrivenSwift/EventListener/EventListenable.swift

@@ -38,7 +38,7 @@ public protocol EventListenable: AnyObject, EventReceivable {
         - forEventType: The `Eventable` Type for which to Register  the Callback
      - Returns: A `UUID` value representing the `token` associated with this Event Callback
      */
-    func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
+    @discardableResult func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID
 
     /**
      Locates and removes the given Listener `token` (if it exists)

Sources/EventDrivenSwift/EventListener/EventListener.swift

@@ -69,7 +69,7 @@ open class EventListener: EventHandler, EventListenable {
         }
     }
 
-    public func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID {
+    @discardableResult public func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) -> UUID {
         let eventTypeName = String(reflecting: forEventType)
         let method: EventCallback = { event, priority in
             self.callTypedEventCallback(callback, forEvent: event, priority: priority)
@@ -145,13 +145,4 @@ open class EventListener: EventHandler, EventListenable {
             callback(typedEvent, priority)
         }
     }
-    
-    /**
-     Initializes an `EventListener`
-     - Author: Simon J. Stuart
-     - Version: 3.0.0
-     */
-    public override init() {
-        super.init()
-    }
 }

Sources/EventDrivenSwift/EventReceiver/EventReceiver.swift

@@ -17,20 +17,6 @@ import Observable
  - 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 EventReceiver: EventHandler, EventReceivable {
-    /**
-     Convienience `typealias` used for Event Callbacks
-     - Author: Simon J. Stuart
-     - Version: 1.0.0
-     */
-    typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority) -> ()
-    
-    /**
-     Convienience `typealias` used for Typed Event Callbacks
-     - Author: Simon J. Stuart
-     - Version: 1.0.0
-     */
-    typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority) -> ()
-    
     /**
      Map of `Eventable` qualified Type Names against `EventCallback` methods.
      - Author: Simon J. Stuart

Tests/EventDrivenSwiftTests/EventListenerTests.swift

@@ -0,0 +1,40 @@
+//
+//  EventListenerTests.swift
+//  
+//
+//  Created by Simon Stuart on 11/08/2022.
+//
+
+import XCTest
+import ThreadSafeSwift
+@testable import EventDrivenSwift
+
+final class EventListenerTests: XCTestCase {
+    struct TestEventTypeOne: Eventable {
+        var foo: Int
+    }
+    let expectedTestOneFoo: Int = 1000
+    var myFoo = 0
+    var awaiter = DispatchSemaphore(value: 0)
+  
+    /// Need a reliable way of Unit Testing this! Anything I do to try to await a result causes this Execution Thread to lock, so the Callback won't occur until *after* the test returns!
+    
+//    func testCentralEventListener() throws {
+//        let listenerToken = TestEventTypeOne.addListener(self) { (event: TestEventTypeOne, priority) in
+//            self.myFoo = event.foo
+//            self.awaiter.signal()
+//        }
+//        // Make sure our Initial Value is as expected
+//        XCTAssertEqual(myFoo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(myFoo)")
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        testOne.queue() // Dispatch the Event
+//
+//        let result = awaiter.wait(timeout: DispatchTime.now().advanced(by: DispatchTimeInterval.seconds(10)))
+//
+//        XCTAssertEqual(result, .success, "The Event Handler was not invoked in time!")
+//
+//        XCTAssertEqual(self.myFoo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(self.myFoo)")
+//        TestEventTypeOne.removeListener(listenerToken)
+//    }
+
+}

Tests/EventDrivenSwiftTests/UIEventReceiverTests.swift

@@ -0,0 +1,115 @@
+//
+//  UIEventReceiverTests.swift
+//  
+//
+//  Created by Simon Stuart on 11/08/2022.
+//
+
+import XCTest
+import ThreadSafeSwift
+@testable import EventDrivenSwift
+
+final class UIEventReceiverTests: XCTestCase {
+    struct TestEventTypeOne: Eventable {
+        var foo: Int
+    }
+    
+    class TestEventThread: UIEventReceiver {
+        @ThreadSafeSemaphore var foo: Int = 0
+        
+        internal func eventOneCallback(_ event: TestEventTypeOne, _ priority: EventPriority) {
+            foo = event.foo
+        }
+        
+        override func registerEventListeners() {
+            addEventCallback(self.eventOneCallback, forEventType: TestEventTypeOne.self)
+        }
+    }
+
+    let expectedTestOneFoo: Int = 1000
+    
+    /// Need a reliable way of Unit Testing this! Anything I do to try to await a result causes this Execution Thread to lock, so the Callback won't occur until *after* the test returns!
+    
+//    func testEventDispatchQueueDirect() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        
+//        eventThread.queueEvent(testOne, priority: .normal) // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+//    
+//    func testEventDispatchQueueCentral() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//        
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        EventCentral.queueEvent(testOne, priority: .normal) // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+//
+//    func testEventDispatchQueueTransparent() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//        
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        
+//        testOne.queue() // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+//    
+//    func testEventDispatchStackDirect() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        
+//        eventThread.stackEvent(testOne, priority: .normal) // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+//    
+//    func testEventDispatchStackCentral() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//        
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        
+//        EventCentral.stackEvent(testOne, priority: .normal) // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+//
+//    func testEventDispatchStackTransparent() throws {
+//        let testOne = TestEventTypeOne(foo: expectedTestOneFoo) // Create the Event
+//        let eventThread = TestEventThread() // Create the Thread
+//        
+//        XCTAssertEqual(eventThread.foo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(eventThread.foo)")
+//        
+//        testOne.stack() // Now let's dispatch our Event to change this value
+//        
+//        let seconds = 1.0
+//        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) {
+//            XCTAssertEqual(eventThread.foo, testOne.foo, "Expect new value of eventThread.foo to be \(testOne.foo), but it's \(eventThread.foo)")
+//        }
+//    }
+}