deavmi/eventy
deavmi
/
eventy
mirror of https://github.com/deavmi/eventy.git
1
0
Fork 0
Code Issues Releases Activity

Completely overhauled Eventy system for the v0.4.0 release 

Removed the event-loop for a better system (for now) whereby we just dispatch signal handlers on the call to `push(Event)`.

In a future release I hope to bring the event loop back but in a signal-based manner, such that we can support deferred events and priorities and such
This commit is contained in:
Tristan B. Velloza Kildaire 2022-11-28 13:39:06 +02:00
parent 6392c92349
commit 7621ee5343
6 changed files with 199 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
README.md
View File

@ -12,45 +12,44 @@ Eventy
### The _engine_
The first thing every Eventy-based application will need is an instance of the `Engine`.
This provides the user with the basic event-loop functionality that eventy provides. It's
the core of the whole framework that exists to have event-triggers ingested into its
_queues_, checking those _queues_ and one by one dispatching each _signal handler_ that
is associated with each queue on each item in the queue.
This provides the user with a single object instance of the [`Engine` class]() by which
the user can register _event types_, _signal handlers_ for said events and the ability
to trigger or _push_ events into the engine.
The simplest way to get a new _engine_ up and running is as follow:
```d
Engine engine = new Engine();
engine.start();
```
This will create a new engine initializing all of its internals and then start it as well.
This will create a new engine initializing all of its internals such that it is ready for
use.
### Queues
### Event types
_Queues_ are as they sound, a list containing items. Each queue has a unique ID which we
can choose. The items of each queue will be the _events_ that are pushed into the _engine_.
An _event_ has an ID associated with it which tells the _engine_ which queue it must be
added to!
_Event types_ are effectively just numbers. The use of these is to be able to connect events
pushed into the engine with their respective signal handlers (which are registered to handle
one or more event types).
Let's create two queues, with IDs `1` and `2`:
Let's create two event types, with IDs `1` and `2`:
```d
engine.addQueue(1);
engine.addQueue(2);
engine.addEventType(new EventType(1));
engine.addEventType(new EventType(2));
```
This will tell the engine to create two new queues with tags `1` and `2` respectively.
This will tell the engine to create two new event types with tags `1` and `2` respectively.
### Event handlers
### Signal handlers
We're almost done. So far we have created a new _engine_ for handling our queues and
the triggering of events. What is missing is something to _handle those queues_ when
they have something added to them, we call this an _"event handler"_ in computer science
but this is Eventy, and in Eventy this is known as a `Signal`.
We're almost done. So far we have created a new _engine_ for handling our event tyoes and
the triggering of events. What is missing is something to _handle those event types_ when
an event of one of those types is pushed into the engine. Such handlers are referred to as
_signal handlers_ and in Eventy these are instances of the [`Signal` class]().
We're going to create a signal that can handle both the queues and perform the same task
for both of them. We do this by creating a class that inherits from the `Signal` base type:
We're going to create a signal that can handle both of the event types `1` and `2` that we
registered earlier on. We can do this by creating a class that inherits from the `Signal`
base class:
```d
class SignalHandler1 : Signal
@ -63,15 +62,15 @@ class SignalHandler1 : Signal
public override void handler(Event e)
{
import std.stdio;
writeln("Running event", e.id);
writeln("Running event", e.getID());
}
}
```
We need to tell the `Signal` class two things:
1. What _queue IDs_ it will handle
2. What to _run_ for said queues
1. What _event typess_ it will handle
2. What to _run_ for said event types
---
@ -92,7 +91,7 @@ two IDs, namely `1` and `2`.
As for _what to run_, that is specified by overriding the `void handler(Event)` method
in the `Signal` class. In our case we make it write to the console the ID of the event
(which would end up either being `1` or `2` seeing as this handler is only registered
for those queue IDs).
for those event types).
```d
import std.stdio;
@ -120,8 +119,6 @@ engine.push(eTest);
eTest = new Event(2);
engine.push(eTest);
```
You will then see something like this:
@ -138,6 +135,20 @@ Running event1
Running event2
```
The reason is it depends on which process gets shceduled by the Linux kernel first, this
is because new threads (special types of processes) are spanwed on the dispatch of each
event.
Despite us pushing the events into the engine in the order of `1` and _then_ `2`, the
scheduling of such threads is up to the Linux kernel and hence one could be run before
the other.
---
## Release notes
### `v0.4.0`
```
Completely overhauled Eventy system for the v0.4.0 release
Removed the event-loop for a better system (for now) whereby we just dispatch signal handlers on the call to `push(Event)`.
In a future release I hope to bring the event loop back but in a signal-based manner, such that we can support deferred events and priorities and such
```

257
source/eventy/engine.d
View File

@ -1,6 +1,6 @@
module eventy.engine;
import eventy.queues : Queue;
import eventy.types : EventType;
import eventy.signal : Signal;
import eventy.event : Event;
import eventy.config;
@ -9,20 +9,20 @@ import eventy.exceptions;
import std.container.dlist;
import core.sync.mutex : Mutex;
import core.thread : Thread, dur, Duration;
import std.conv : to;
unittest
{
import std.stdio;
Engine engine = new Engine();
engine.start();
/**
* Let the event engine know what typeIDs are
* allowed to be queued
*/
engine.addQueue(1);
engine.addQueue(2);
engine.addEventType(new EventType(1));
engine.addEventType(new EventType(2));
/**
* Create a new Signal Handler that will handles
@ -38,7 +38,7 @@ unittest
public override void handler(Event e)
{
writeln("Running event", e.id);
writeln("Running event", e.getID());
}
}
@ -60,7 +60,7 @@ unittest
writeln("done with main thread code");
while(engine.hasPendingEvents()) {}
while(engine.hasEventsRunning()) {}
/* TODO: Before shutting down, actually test it out (i.e. all events ran) */
engine.shutdown();
@ -72,14 +72,13 @@ unittest
EngineSettings customSettings = {holdOffMode: HoldOffMode.YIELD};
Engine engine = new Engine(customSettings);
engine.start();
/**
* Let the event engine know what typeIDs are
* allowed to be queued
*/
engine.addQueue(1);
engine.addQueue(2);
engine.addEventType(new EventType(1));
engine.addEventType(new EventType(2));
/**
* Create a new Signal Handler that will handles
@ -95,7 +94,7 @@ unittest
public override void handler(Event e)
{
writeln("Running event", e.id);
writeln("Running event", e.getID());
}
}
@ -117,7 +116,7 @@ unittest
writeln("done with main thread code");
while(engine.hasPendingEvents()) {}
while(engine.hasEventsRunning()) {}
/* TODO: Before shutting down, actually test it out (i.e. all events ran) */
engine.shutdown();
@ -133,14 +132,12 @@ unittest
* handlers, add signal handlers, among many
* other things
*/
public final class Engine : Thread
public final class Engine
{
/* TODO: Or use a queue data structure */
/* Registered queues */
private DList!(Queue) queues;
private Mutex queueLock;
private DList!(EventType) eventTypes;
private Mutex eventTypesLock;
/* TODO: Or use a queue data structure */
/* Registered signal handlers */
private DList!(Signal) handlers;
private Mutex handlerLock;
@ -164,9 +161,7 @@ public final class Engine : Thread
*/
this(EngineSettings settings)
{
super(&run);
queueLock = new Mutex();
eventTypesLock = new Mutex();
handlerLock = new Mutex();
threadStoreLock = new Mutex();
@ -238,74 +233,6 @@ public final class Engine : Thread
handlerLock.unlock();
}
/**
* The main event loop
*
* This checks at a certain interval (see HoldOffMode) if
* there are any events in any of the queues, if so,
* the dispatcher for said event type is called
*/
private void run()
{
running = true;
while (running)
{
/**
* Lock the queue-set
*
* TODO: Maybe add sleep support here too?
*/
while (!queueLock.tryLock_nothrow())
{
// Don't waste time spinning on mutex, yield if failed
if(!settings.agressiveTryLock)
{
yield();
}
}
foreach (Queue queue; queues)
{
/* If the queue has evenets queued */
if (queue.hasEvents())
{
/* TODO: Add different dequeuing techniques */
/* Pop the first Event */
Event headEvent = queue.popEvent();
/* Get all signal-handlers for this event type */
Signal[] handlersMatched = getSignalsForEvent(headEvent);
/* Dispatch the signal handlers */
dispatch(handlersMatched, headEvent);
}
}
/* Unlock the queue set */
queueLock.unlock();
/* Activate hold off (dependening on the type) */
if(settings.holdOffMode == HoldOffMode.YIELD)
{
/* Yield to stop mutex starvation */
yield();
}
else if(settings.holdOffMode == HoldOffMode.SLEEP)
{
/* Sleep the thread (for given time) to stop mutex starvation */
sleep(settings.sleepTime);
}
else
{
/* This should never happen */
assert(false);
}
}
}
/**
* Shuts down the event engine
*/
@ -319,11 +246,8 @@ public final class Engine : Thread
/* Wait for any pendings events (if configured) */
if(settings.gracefulShutdown)
{
while(hasPendingEvents()) {}
while(hasEventsRunning()) {}
}
/* Stop the loop */
running = false;
}
/**
@ -335,12 +259,9 @@ public final class Engine : Thread
*/
private void dispatch(Signal[] signalSet, Event e)
{
/* TODO: Add ability to dispatch on this thread */
foreach (Signal signal; signalSet)
{
/* Create a new Thread */
// Thread handlerThread = getThread(signal, e);
DispatchWrapper handlerThread = new DispatchWrapper(signal, e);
/**
@ -407,6 +328,29 @@ public final class Engine : Thread
threadStoreLock.unlock();
}
/**
* Checks whether or not there are still events
* running at the time of calling
*
* Returns: <code>true</code> if there are events
* still running, <code>false</code> otherwise
*/
public bool hasEventsRunning()
{
/* Whether there are events running or not */
bool has = false;
/* Lock the thread store */
threadStoreLock.lock();
has = !threadStore.empty();
/* Unlock the thread store */
threadStoreLock.unlock();
return has;
}
/**
* DispatchWrapper
*
@ -455,7 +399,7 @@ public final class Engine : Thread
/* Find all handlers matching */
foreach (Signal signal; handlers)
{
if (signal.handles(e.id))
if (signal.handles(e.getID()))
{
matchedHandlers ~= signal;
}
@ -473,7 +417,8 @@ public final class Engine : Thread
*
* Params:
* id = the event ID to check
* Returns:
* Returns: <code>true</code> if a signal handler does
* exist, <code>false</code> otherwise
*/
public bool isSignalExists(ulong id)
{
@ -489,78 +434,100 @@ public final class Engine : Thread
*/
public void push(Event e)
{
Queue matchedQueue = findQueue(e.id);
//TODO: New code goes below here
/**
* What we want to do here is to effectively
* wake up a checker thread and also (before that)
* perhaps we say what queue was modified
*
* THEN the checker thread goes to said queue and
* executes said event (dispatches it) and then sleep
* again till it is interrupted. We need Pids and kill etc for this
*
* Idea (2)
*
* If we cannot do a checker thread then we can spwan a thread here
* but then we get no control for priorities etc, although actually we could
* maybe? It depends, we don't want multiple dispathers at same time then
* (A checker thread would ensure we don't get this)
*/
if (matchedQueue)
/* Obtain all signal handlers for the given event */
Signal[] handlersMatched = getSignalsForEvent(e);
/* If we get signal handlers then dispatch them */
if(handlersMatched.length)
{
/* Append to the queue */
matchedQueue.add(e);
dispatch(handlersMatched, e);
}
/* If there are no matching events */
else
{
//TODO: Add default handler support
//TODO: Add error throwing in case where not true
}
}
/**
* Creates a new queue with the given id
* Registers a new EventType with the engine
* and then adds it.
*
* Throws EventyException if the id is already
* in use by another queue
* Throws EventyException if the id of the given
* EventType is is already in use by another
*
* Params:
* id = the id of the neq eueue to create
* id = the id of the new event type to add
* Throws: EventyException
*/
public void addQueue(ulong id)
public void addEventType(EventType evType)
{
/* Create a new queue with the given id */
Queue newQueue = new Queue(id);
/* Lock the queue collection */
queueLock.lock();
/* Lock the event types list */
eventTypesLock.lock();
/* If no such queue exists then add it (recursive mutex used) */
if (!findQueue(id))
if (!findEventType(evType.getID()))
{
/* Add the queue */
queues ~= newQueue;
/* Add the event types list */
eventTypes ~= evType;
}
else
{
throw new EventyException("Failure to add queue with ID already in use");
throw new EventyException("Failure to add EventType with id '"~to!(string)(evType.getID())~"\' as it is already in use");
}
/* Unlock the queue collection */
queueLock.unlock();
/* Unlock the event types list */
eventTypesLock.unlock();
}
/**
* Given an if, this will return the Queue
* Given an if, this will return the EventType
* associated with said id
*
* Params:
* id = the id of the Queue
* Returns: The Queue if found, otherwise
* id = the id of the EventType
* Returns: The EventType if found, otherwise
* <code>null</code>
*/
public Queue findQueue(ulong id)
public EventType findEventType(ulong id)
{
/* Lock the queue collection */
queueLock.lock();
/* Lock the EventType list */
eventTypesLock.lock();
/* Find the matching queue */
Queue matchedQueue;
foreach (Queue queue; queues)
/* Find the matching EventType */
EventType matchedEventType;
foreach (EventType eventType; eventTypes)
{
if (queue.id == id)
if (eventType.getID() == id)
{
matchedQueue = queue;
matchedEventType = eventType;
break;
}
}
/* Unlock the queue collection */
queueLock.unlock();
/* Unlock the EventType list */
eventTypesLock.unlock();
return matchedQueue;
return matchedEventType;
}
/* TODO: Add coumentation */
@ -569,34 +536,4 @@ public final class Engine : Thread
/* TODO: Implement me */
return null;
}
/**
* Checks if any of the queues in the event engine
* have any pending events in them waiting dispatch
*
* Returns: <code>true</code> if there are pending events,
* <code>false</code> otherwise
*/
public bool hasPendingEvents()
{
bool isPending = false;
/* Lock the queues */
queueLock.lock();
foreach (Queue queue; queues)
{
if (queue.hasEvents())
{
isPending = true;
break;
}
}
/* Unlock the queues */
queueLock.unlock();
return isPending;
}
}

31
source/eventy/event.d
View File

@ -5,23 +5,30 @@ module eventy.event;
*
* An Event represents a trigger for a given signal(s)
* handlers which associate with the given typeID
*
* It can optionally take a payload with it as well
*/
public class Event
{
/**
* Creates a new Event, optionally taking with is a
* payload
*/
this(ulong typeID, ubyte[] payload = null)
/* The event's type id */
private ulong id;
/**
* Creates a new Event with the given typeID
*
* Params:
* typeID = the new Event's type ID
*/
this(ulong typeID)
{
this.id = typeID;
this.payload = payload;
}
ulong id;
ubyte[] payload;
// TODO: Remove the requirement for the payload
/**
* Returns the type ID of this Event
*
* Returns: The Event's type ID
*/
public final ulong getID()
{
return id;
}
}

2
source/eventy/package.d
View File

@ -3,6 +3,6 @@ module eventy;
public import eventy.event;
public import eventy.exceptions;
public import eventy.engine;
public import eventy.queues;
public import eventy.types;
public import eventy.signal;
public import eventy.config;

75
source/eventy/queues.d
View File

@ -1,75 +0,0 @@
module eventy.queues;
import eventy.event : Event;
import core.sync.mutex : Mutex;
import std.container.dlist;
import std.range;
/**
* Queue
*
* Represents a queue with a given ID that can
* have Event-s enqueued to it
*/
public final class Queue
{
public ulong id;
/* TODO: Add queue of Event's here */
private DList!(Event) queue;
private Mutex queueLock;
this(ulong id)
{
this.id = id;
queueLock = new Mutex();
}
public DList!(Event).Range getKak()
{
return queue[];
}
public void add(Event e)
{
/* Lock the queue */
queueLock.lock();
queue.insert(e);
/* Unlock the queue */
queueLock.unlock();
}
public bool hasEvents()
{
bool has;
/* Lock the queue */
queueLock.lock();
has = !(queue[]).empty();
/* Unlock the queue */
queueLock.unlock();
return has;
}
public Event popEvent()
{
Event poppedEvent;
/* Lock the queue */
queueLock.lock();
poppedEvent = (queue[]).front();
queue.removeFront();
/* Unlock the queue */
queueLock.unlock();
return poppedEvent;
}
}

40
source/eventy/types.d Normal file
View File

@ -0,0 +1,40 @@
module eventy.types;
import eventy.event : Event;
import core.sync.mutex : Mutex;
import std.container.dlist;
import std.range;
/**
* EventType
*
* Represents a type of event. Every Event has an EventType
* and Signal(s)-handlers register to one or more of these
* types to handle
*/
public final class EventType
{
/* The EventType's ID */
private ulong id;
/**
* Instantiates a new EventType with the given id
*
* Params:
* id = The EventType's id
*/
this(ulong id)
{
this.id = id;
}
/**
* Returns the id of this EventType
*
* Returns: The id of this EventType
*/
public ulong getID()
{
return id;
}
}