EventListener enhancements

- `EventListener` can now invoke Callbacks on any of 3 Target Threads:
  - `.requesterThread` is the Thread belonging to the Callback itself
  - `.listenerThread` is the Thread belonging to the `EventListener`
  - `.taskThread` is an Ad-hoc `Task` Thread
- README.MD updated for the above

Author: LK-Simon

README.md

@@ -125,7 +125,7 @@ let package = Package(
     dependencies: [
         .package(
             url: "https://github.com/Flowduino/EventDrivenSwift.git",
-            .upToNextMajor(from: "3.0.0")
+            .upToNextMajor(from: "3.1.0")
         ),
     ],
     //...
@@ -355,7 +355,7 @@ An `EventListener` is a universal way of subscribing to *Events*, anywhere in yo
 
 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.
+**Important Note:** `EventListener` will (by default) 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.
 
@@ -386,6 +386,19 @@ In the above example, whenever the *Reciprocal Event* named `TemperatureRatingEv
 
 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!
 
+If you need your *Event Callback* to execute on the *Listener's* Thread, as of Version 3.1.0... you can!
+```swift
+listenerToken = TemperatureRatingEvent.addListener(self, onTemperatureRatingEvent, executeOn: .listenerThread)
+```
+**Remember:** When executing an *Event Callback* on `.listenerThread`, you will need to ensure that your *Callback* and all resources that it uses are 100% Thread-Safe!
+**Important:** Executing the *Event Callback* on `.listnerThread` can potentially delay the invocation of other *Event Callbacks*. Only use this option when it is necessary.
+
+You can also execute your *Event Callback* on an ad-hoc `Task`:
+```swift
+listenerToken = TemperatureRatingEvent.addListener(self, onTemperatureRatingEvent, executeOn: .taskThread)
+```
+**Remember:** When executing an *Event Callback* on `.taskThread`, you will need to ensure that your *Callback* and all resources that it uses are 100% Thread-Safe!
+
 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)

Sources/EventDrivenSwift/Central/EventCentral.swift

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

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) -> UUID
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> UUID
 
     /**
      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>) -> UUID
+    @discardableResult static func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, executeOn: ExecuteEventOn) -> UUID
 
     /**
      Locates and removes the given Listener `token` (if it exists) from the Central Event Listener
@@ -80,8 +80,8 @@ extension Eventable {
         EventCentral.stackEvent(self, priority: priority)
     }
 
-    @discardableResult static public func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>) -> UUID {
-        return EventCentral.addListener(requester, callback, forEventType: Self.self)
+    @discardableResult static public func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, executeOn: ExecuteEventOn = .requesterThread) -> UUID {
+        return EventCentral.addListener(requester, callback, forEventType: Self.self, executeOn: executeOn)
     }
 
     public static func removeListener(_ token: UUID) {

Sources/EventDrivenSwift/EventListener/EventListenable.swift

@@ -22,6 +22,28 @@ typealias EventCallback = (_ event: any Eventable, _ priority: EventPriority) ->
  */
 public typealias TypedEventCallback<TEvent: Any> = (_ event: TEvent, _ priority: EventPriority) -> ()
 
+public enum ExecuteEventOn {
+    /**
+     Callback will execute on the context of the Requester's own Thread
+     - Author: Simon J. Stuart
+     - Version: 3.1.0
+     */
+    case requesterThread
+    /**
+     Callback will execute on the context of the Listener's Thread
+     - Author: Simon J. Stuart
+     - Version: 3.1.0
+     - Note: You must ensure your Callback (and all resources it uses) are Thread-Safe!
+     */
+    case listenerThread
+    /**
+     Callback will execute on the context of an ad-hoc Task
+     - Author: Simon J. Stuart
+     - Version: 3.1.0
+     - Note: You must ensure your Callback (and all resources it uses) are Thread-Safe!
+     */
+    case taskThread
+}
 /**
  Provides a simple means of Receiving Events and invoking appropriate Callbacks
  - Author: Simon J. Stuart
@@ -36,9 +58,10 @@ public protocol EventListenable: AnyObject, EventReceivable {
         - requester: The Object owning the Callback Method
         - callback: The code to invoke for the given `Eventable` Type
         - forEventType: The `Eventable` Type for which to Register  the Callback
+        - 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) -> UUID
+    @discardableResult func addListener<TEvent: Eventable>(_ requester: AnyObject, _ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type, executeOn: ExecuteEventOn) -> UUID
 
     /**
      Locates and removes the given Listener `token` (if it exists)

Sources/EventDrivenSwift/EventListener/EventListener.swift

@@ -27,6 +27,7 @@ open class EventListener: EventHandler, EventListenable {
         weak var requester: AnyObject?
         var callback: EventCallback
         var dispatchQueue: DispatchQueue?
+        var executeOn: ExecuteEventOn = .requesterThread
     }
 
     /**
@@ -61,20 +62,28 @@ open class EventListener: EventHandler, EventListenable {
                 removeListener(listener.token, typeOf: type(of: event)) // ... Unregister this Listener
                 continue // Skip this one
             }
-            // Execute the Callback on the Listener's own Dispatch Queue
-            let dispatchQueue = listener.dispatchQueue ?? DispatchQueue.main
-            dispatchQueue.async {
+            switch listener.executeOn {
+            case .requesterThread:
+                let dispatchQueue = listener.dispatchQueue ?? DispatchQueue.main
+                dispatchQueue.async {
+                    listener.callback(event, priority)
+                }
+            case .listenerThread:
                 listener.callback(event, priority)
+            case .taskThread:
+                Task {
+                    listener.callback(event, priority)
+                }
             }
         }
     }
 
-    @discardableResult 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, executeOn: ExecuteEventOn = .requesterThread) -> UUID {
         let eventTypeName = String(reflecting: forEventType)
         let method: EventCallback = { event, priority in
             self.callTypedEventCallback(callback, forEvent: event, priority: priority)
         }
-        let eventListenerContainer = EventListenerContainer(requester: requester, callback: method, dispatchQueue: OperationQueue.current?.underlyingQueue)
+        let eventListenerContainer = EventListenerContainer(requester: requester, callback: method, dispatchQueue: OperationQueue.current?.underlyingQueue, executeOn: executeOn)
         _eventListeners.withLock { eventCallbacks in
             var bucket = eventCallbacks[eventTypeName]
             if bucket == nil { bucket = [EventListenerContainer]() } // Create a new bucket if there isn't already one!