Terminology

Understanding the Terminology used in this Library and its supporting examples/documentation will aid you considerably in immediately leveraging these tools to produce extremely powerful, high-performance, entirely-decoupled and easily maintained Event-Driven solutions.

Event

An Event is simply an immutable payload of information that can be used to drive logic and behaviour.

Think of an Event as being akin to an Operation Trigger. In response to receiving an Event of a known Type, a distinct unit of code would perform an appropriate operation based on the information received in that Event's Payload.

In EventDrivenSwift, we would typically define an Event as a struct conforming to the Eventable protocol.

Here is a simple example:

struct TemperatureEvent: Eventable {
    var temperatureInCelsius: Float
}

Note that the above example, TemperatureEvent, is the most basic example of an Event possible, in that it only contains one piece of information. In reality, your Events can encapsulate as much information as is logical for a single cohesive operation trigger.

Important Note: An Event should never include any Reference-Type values (such as class instances). Events need to be immutable, meaning that none of their values can possibly change after they have been Dispatched. It is, however, sometimes - by exception, not by rule - acceptable to include a weak reference to an Object (class or other Reference Type) where such a reference may be relevant to the processing of that Event by a Listener or EventThread.

Event Queue

An Event Queue is a sequencial collection (Array) of Eventable objects that will automatically be processed whenever the Queue is not empty. Queues are always processed in the order First-in-First-out (or FiFo).

Note that Events dispatched to a Queue will always be processed after Events dispatched to a Stack.

Event Stack

An Event Stack is virtually the same as an Event Queue, except that it is processed in the opposite order: Last-in-First-out (or LiFo)

Note that Events dispatched to a Stack will always be processed before Events dispatched to a Queue.

Event Priority

Events can be dispatched to a Queue or Stack with one of the following Priorities: .highest will be processed first .high will be processed second .normal will be processed third .low will be processed fourth .lowest will be processed last

This means that we can enforce some degree of execution order over Events at the point of dispatch.

Dispatch

Dispatch is a term comparable to Broadcast. When we Dispatch an Event, it means that we are sending that information to every EventThread and Event Listener that is listening for that Event type.

Once an Event has been Dispatched, it cannot be cancelled or modified. This is by design. Think of it as saying that "you cannot unsay something once you have said it."

Events can be Dispatched from anywhere in your code, regardless of what Thread is invoking it. In this sense, Events are very much a fire and forget process.

Event Listener

An Event Listener is, essentially, a Callback method that you can define as part of any class, which will be invoked each time an Event of the associated Type is Dispatched from anywhere in your code.

Event Listeners are a crucial feature of EventDrivenSwift, because they can be quickly and easily added anywhere you require them within your existing codebase.

EventThread

An EventThread is a class inheriting the base type provided by this library called EventThread.

Beneath the surface, EventThread descends from Thread, and is literally what is known as a Persistent Thread. This means that the Thread would typically exist either for a long as your particular application would require it, or even for the entire lifetime of your application.

Unlike most Threads, EventThread has been built specifically to operate with the lowest possible system resource footprint. When there are no Events waiting to be processed by your EventThread, the Thread will consume absolutely no CPU time, and effectively no power at all.

Once your EventThread receives an Event of an Eventable type to which it has subscribed (is listening for), it will wake up automatically and process any waiting Events in its respective Queue and Stack.

Note: any number of EventThreads can receive the same Events. This means that you can process the same Event for any number of purposes, in any number of ways, with any number of outcomes.

Event Handler (or Callback)

When you define your EventThread descendant, you will implement a function called registerEventListeners. Within this function (which is invoked automatically every time an Instance of your EventThread descendant type is initialised) you will register the Eventable Types to which your EventThread is interested; and for each of those, define a suitable Handler (or Callback) method to process those Events whenever they occur.

For each Eventable type that your EventThread is interested in processing, you will be able to register your Event Handler for that Event type in a single line of code.

This makes it extremely easy to manage and maintain the Event Subscriptions that each EventThread has been implemented to process.