Event Scheduling added

- Event Scheduling has been added throughout the system.
- Unit Test coverage for Event Scheduling has also been added.

Author: LK-Simon

Sources/EventDrivenSwift/Central/EventCentral.swift

@@ -16,6 +16,7 @@ Singleton for the Central Event Dispatcher.
  - Note: This is used when invoking the `queue` and `stack` methods of `Eventable`.
  */
 final public class EventCentral: EventDispatcher, EventCentralable {
+    
     /**
      Singleton Instance of our Central Event Dispatcher
      - Author: Simon J. Stuart
@@ -86,6 +87,14 @@ final public class EventCentral: EventDispatcher, EventCentralable {
         _shared.eventListener.removeListener(token, typeOf: typeOf)
     }
 
+    @inline(__always) static public func scheduleQueue(_ event: Eventable, at: DispatchTime, priority: EventPriority) {
+        _shared.scheduleQueue(event, at: at, priority: priority)
+    }
+    
+    @inline(__always) static public func scheduleStack(_ event: Eventable, at: DispatchTime, priority: EventPriority) {
+        _shared.scheduleStack(event, at: at, priority: priority)
+    }
+    
     /// This just makes it so that your code cannot initialise instances of `EventCentral`. It's a Singleton!
     override private init() {}
 }

Sources/EventDrivenSwift/Central/EventCentralable.swift

@@ -89,4 +89,24 @@ public protocol EventCentralable {
         - typeOf: The Event Type for which the Listener identified by the given `token` is interested
      */
     static func removeListener(_ token: UUID, typeOf: Eventable.Type)
+    
+    /**
+     Schedule the Event to be dispatched through the Central Queue with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    static func scheduleQueue(_ event: Eventable, at: DispatchTime, priority: EventPriority)
+    
+    /**
+     Schedule the Event to be dispatched through the Central Stack with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    static func scheduleStack(_ event: Eventable, at: DispatchTime, priority: EventPriority)
 }

Sources/EventDrivenSwift/Event/Eventable.swift

@@ -34,6 +34,26 @@ public protocol Eventable {
      */
     func stack(priority: EventPriority)
 
+    /**
+     Schedule the Event to be dispatched through the Central Queue with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    func scheduleQueue(at: DispatchTime, priority: EventPriority)
+    
+    /**
+     Schedule the Event to be dispatched through the Central Stack with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    func scheduleStack(at: DispatchTime, priority: EventPriority)
+    
     /**
      Registers an Event Listner Callback for the given `Eventable` Type with the Central Event Listener
      - Author: Simon J. Stuart
@@ -74,14 +94,22 @@ extension Eventable {
  - Version: 1.0.0
  */
 extension Eventable {
-    public func queue(priority: EventPriority = .normal) {
+    @inline(__always) public func queue(priority: EventPriority = .normal) {
         EventCentral.queueEvent(self, priority: priority)
     }
 
-    public func stack(priority: EventPriority = .normal) {
+    @inline(__always) public func stack(priority: EventPriority = .normal) {
         EventCentral.stackEvent(self, priority: priority)
     }
 
+    @inline(__always) public func scheduleQueue(at: DispatchTime, priority: EventPriority = .normal) {
+        EventCentral.scheduleQueue(self, at: at, priority: priority)
+    }
+    
+    @inline(__always) public func scheduleStack(at: DispatchTime, priority: EventPriority = .normal) {
+        EventCentral.scheduleStack(self, at: at, priority: priority)
+    }
+    
     @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/EventHandler/EventHandler.swift

@@ -93,6 +93,23 @@ open class EventHandler: ObservableThread, EventHandling {
         eventsPending.signal()
     }
 
+    public func scheduleQueue(_ event: any Eventable, at: DispatchTime, priority: EventPriority) {
+        Task {
+            DispatchQueue.main.asyncAfter(deadline: at) {
+                self.queueEvent(event, priority: priority)
+            }
+        }
+    }
+    
+    public func scheduleStack(_ event: any Eventable, at: DispatchTime, priority: EventPriority) {
+        Task {
+            DispatchQueue.main.asyncAfter(deadline: at) {
+                self.stackEvent(event, priority: priority)
+            }
+        }
+    }
+    
+    
     /**
      Processes an Event
      - Author: Simon J. Stuart

Sources/EventDrivenSwift/EventHandler/EventHandling.swift

@@ -34,6 +34,26 @@ public protocol EventHandling {
      */
     func stackEvent(_ event: any Eventable, priority: EventPriority)
 
+    /**
+     Schedule the Event to be dispatched with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    func scheduleQueue(_ event: any Eventable, at: DispatchTime, priority: EventPriority)
+    
+    /**
+     Schedule the Event to be dispatched with the given `priority`
+     - Author: Simon J. Stuart
+     - Version: 4.2.0
+     - Parameters:
+        - at: The `DispatchTime` after which to dispatch the Event
+        - priority: The `EventPriority` with which to process the Event
+     */
+    func scheduleStack(_ event: any Eventable, at: DispatchTime, priority: EventPriority)
+    
     /**
      The number of Events currently pending in the Queue and Stack combined
      - Author: Simon J. Stuart

Tests/EventDrivenSwiftTests/BasicEventSchedulingTests.swift

@@ -0,0 +1,47 @@
+//
+//  BasicEventSchedulingTests.swift
+//  
+//
+//  Created by Simon Stuart on 28/08/2022.
+//
+
+import XCTest
+import ThreadSafeSwift
+@testable import EventDrivenSwift
+
+final class BasicEventSchedulingTests: XCTestCase {
+    private struct TestEvent: Eventable {
+        public var foo: String
+    }
+    
+    @ThreadSafeSemaphore private var testValue: String = "Hello"
+    private var exp: XCTestExpectation? = nil
+    private var executed: DispatchTime? = nil
+    
+    func testPerformanceExample() throws {
+        TestEvent.addListener(self, { (event: TestEvent, priority) in
+            print("TestEvent where foo = \(event.foo)")
+            self.testValue = event.foo
+            self.executed = DispatchTime.now()
+            self.exp?.fulfill()
+        }, executeOn: .taskThread)
+        
+        exp = expectation(description: "Event Executed")
+        
+        XCTAssertEqual(testValue, "Hello")
+        let scheduledFor = DispatchTime.now() + TimeInterval().advanced(by: 4)  // Schedule for T+5 seconds
+        TestEvent(foo: "World").scheduleQueue(at: scheduledFor)
+        
+        let result = XCTWaiter.wait(for: [exp!], timeout: 5.0)
+        
+        XCTAssertNotEqual(result, .timedOut)
+        
+        XCTAssertEqual(testValue, "World")
+        XCTAssertNotNil(executed)
+        if executed != nil {
+            XCTAssertLessThan(scheduledFor, executed!)
+            XCTAssertLessThan(executed!, scheduledFor + TimeInterval().advanced(by: 4.001))
+        }
+    }
+
+}