Improved Listeners by making them return a Handler

UUID tokens for `EventListener.addListener` have been replaced by a new `EventListenerHandling` protocol describing the `EventListenerHandler` class. This can be used to call `.remove()` and unregister the `Listener`.

References are `weak`, and perform `nil`-checks as appropriate, so calling `.remove()` against an `EventListenerHandler` for an `EventListenable` that has been garbage collected won't raise any errors.

Author: LK-Simon

Sources/EventDrivenSwift/Central/EventCentral.swift

@@ -74,7 +74,7 @@ final public class EventCentral: EventDispatcher, EventCentralable {
         }
     }
 
-    @discardableResult @inline(__always) public static func addListener<TEvent>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn = .requesterThread) -> UUID where TEvent : Eventable {
+    @discardableResult @inline(__always) public static func addListener<TEvent>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn = .requesterThread) -> EventListenerHandling where TEvent : Eventable {
         return _shared.eventListener.addListener(requester, callback, forEventType: forEventType, executeOn: executeOn)
     }
 

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
      */
-    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> UUID
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> EventListenerHandling
 
     /**
      Locates and removes the given Listener `token` (if it exists) from the Central Event Listener

Sources/EventDrivenSwift/Event/Eventable.swift

@@ -43,7 +43,7 @@ public protocol Eventable {
         - 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>, executeOn: ExecuteEventOn) -> UUID
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, executeOn: ExecuteEventOn) -> EventListenerHandling
 
 //    @discardableResult static func addListener(_ requester: AnyObject?, _ eventType: any Eventable.Type, _ callback: @escaping TypedEventCallback<any Eventable.Type>, executeOn: ExecuteEventOn) -> UUID
 
@@ -82,7 +82,7 @@ extension Eventable {
         EventCentral.stackEvent(self, priority: priority)
     }
 
-    @discardableResult static public func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, executeOn: ExecuteEventOn = .requesterThread) -> UUID {
+    @discardableResult static public func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, executeOn: ExecuteEventOn = .requesterThread) -> EventListenerHandling {
         return EventCentral.addListener(requester, callback, forEventType: Self.self, executeOn: executeOn)
     }
 

Sources/EventDrivenSwift/EventListener/EventListenable.swift

@@ -61,7 +61,7 @@ public protocol EventListenable: AnyObject, EventReceiving {
         - executeOn: Tells the `EventListenable` whether to execute the Callback on the `requester`'s Thread, or the Listener's.
      - Returns: A `UUID` value representing the `token` associated with this Event Callback
      */
-    @discardableResult func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> UUID
+    @discardableResult func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> EventListenerHandling
 
     /**
      Locates and removes the given Listener `token` (if it exists)

Sources/EventDrivenSwift/EventListener/EventListener.swift

@@ -80,7 +80,7 @@ open class EventListener: EventHandler, EventListenable {
         }
     }
 
-    @discardableResult public func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn = .requesterThread) -> UUID {
+    @discardableResult public func addListener<TEvent: Eventable>(_ requester: AnyObject?, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn = .requesterThread) -> EventListenerHandling {
         let eventTypeName = String(reflecting: forEventType)
         let method: EventCallback = { event, priority in
             self.callTypedEventCallback(callback, forEvent: event, priority: priority)
@@ -95,7 +95,7 @@ open class EventListener: EventHandler, EventListenable {
 
         /// We automatically register the Listener with the Central Event Dispatcher
         EventCentral.shared.addReceiver(self, forEventType: forEventType)
-        return eventListenerContainer.token
+        return EventListenerHandler(eventListenable: self, token: eventListenerContainer.token)
     }
 
     public func removeListener(_ token: UUID) {

Sources/EventDrivenSwift/EventListener/EventListening.swift

@@ -8,6 +8,11 @@
 
 import Foundation
 
+/**
+ Apply `EventListening` to any `Class` intent on listening for `Eventable`s to register `@EventMethod`-decorated (immutable) Listeners via Reflection.
+ - Author: Simon J. Stuart
+ - Version: 4.1.0
+ */
 public protocol EventListening: AnyObject {
     /**
      Invoke this method to automatically register any Event Listener callback bearing the `@EventMethod` wrapper.

Sources/EventDrivenSwift/EventListener/Handler/EventListenerHandler.swift

@@ -0,0 +1,38 @@
+//
+// EventListenerHandler.swift
+// Copyright (c) 2022, Flowduino
+// Authored by Simon J. Stuart on 28th August 2022
+//
+// Subject to terms, restrictions, and liability waiver of the MIT License
+//
+
+import Foundation
+
+/**
+ A Handler for an `EventListener` your code has registered. You can use this to revoke your Event Listeners at any time.
+ - Author: Simon J. Stuart
+ - Version: 4.1.0
+ */
+public class EventListenerHandler: EventListenerHandling {
+    /**
+     `weak` reference to the `EventListenable` against which this Listener is registered.
+     - Author: Simon J. Stuart
+     - Version: 4.1.0
+     */
+    private weak var eventListenable: EventListenable?
+    
+    /**
+     This is the Token Key assoicated with your Listener
+     - Author: Simon J. Stuart
+     - Version: 4.1.0
+     */
+    private var token: UUID
+    
+    public func remove() {
+        eventListenable?.removeListener(token)
+    }
+    
+    public init(eventListenable: EventListenable, token: UUID) {
+        self.token = token
+    }
+}

Sources/EventDrivenSwift/EventListener/Handler/EventListenerHandling.swift

@@ -0,0 +1,21 @@
+//
+// EventListenerHandling.swift
+// Copyright (c) 2022, Flowduino
+// Authored by Simon J. Stuart on 28th August 2022
+//
+// Subject to terms, restrictions, and liability waiver of the MIT License
+//
+
+import Foundation
+
+/**
+ A Handler for an `EventListener` your code has registered. You can use this to revoke your Event Listeners at any time.
+ - Author: Simon J. Stuart
+ - Version: 4.1.0
+ */
+public protocol EventListenerHandling: AnyObject {
+    /**
+     Removes your Event Listener
+     */
+    func remove()
+}

Tests/EventDrivenSwiftTests/BasicEventListenerTests.swift

@@ -35,15 +35,15 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
     }
 
     var myFoo = 0
-    var listenerToken: UUID? = nil
+    var listenerHandler: EventListenerHandling? = nil
     let testOne = TestEventTypeOne(foo: 1000) // Create the Event
     var awaiter = DispatchSemaphore(value: 0)
 
     func testEventListenerOnListenerThread() throws {
         registerListeners()
         XCTAssertEqual(myFoo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(myFoo)")
 
-        listenerToken = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
+        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
             self.myFoo = event.foo
             self.awaiter.signal()
         }, executeOn: .listenerThread)
@@ -56,14 +56,14 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
         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!)
+        listenerHandler?.remove()
     }
 
     func testEventListenerOnTaskThread() throws {
 //        registerListeners()
         XCTAssertEqual(myFoo, 0, "Expect initial value of eventThread.foo to be 0, but it's \(myFoo)")
 
-        listenerToken = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
+        listenerHandler = TestEventTypeOne.addListener(self, { (event: TestEventTypeOne, priority) in
             self.myFoo = event.foo
             self.awaiter.signal()
         }, executeOn: .taskThread)
@@ -74,6 +74,6 @@ final class BasicEventListenerTests: XCTestCase, EventListening {
         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!)
+        listenerHandler?.remove()
     }
 }