An event is the fact that a certain point in the code and the value of certain variables, which are accessible at that point in the code for reading, is reached. The content of these known variables is called the event data.
[--Example:
if (a >= 3 && a <= 4 && strcmp(s, "foobar"))
{
handle_event(a, s); // Reaching this point means that the event happened.
// The `event data' is `a' and `s'.
}
--End of example]
An event type is the definition of the variables associated with an event, the event data, and the range of these variables. This range may be limited to a part of the total variable space.
[--Example: In the above example, the event type is
int a; // a == 3 || a == 4
char* s; // s is "bar" or "foo" or "barfoo" (determined by
// previous code that lead to the event).
If `s' is known to have only a limited set of values, for instance "aaa", "bbb" or "ccc", then that is part of the event type too.
--End of example]
An event needs to be passed to zero or more objects by calling a method of those objects. Those objects are called event clients.
All or a part of the event data may be needed to be passed to the event clients to describe the event.
[--Example:
if (3 < x && x < 7 && 9 < y && y < 20)
{
cl_obj.event37920(x, y); // `cl_obj' is a `event client'.
}
--End of example]
No data is returned from the event clients.
An event is not dependant of the state of event client(s).
The member function call at the place in the code that signifies the event is called the event trigger.
[--Example:
if (3 < x && x > 7 && 9 < y && 20 > y)
{
event_server.handle_event(EVENT_37920, x, y); // `handle_event' is the `event trigger'
}
--End of example]
The object that calls the event trigger method is called the event generator.
The object that owns the event trigger method is the event server.
An event client can optionally pass a busy interface object along with its request for an event.
This busy interface object gets probed by the event server to see if the client is busy for that event type (it is possible to specify different busy interfaces per event request).
If the event client is not busy on that particular busy interface and an event occurs of that type, then the client must accept the event and process it immediately, before returning. If the busy interface is marked busy it must queue the event and return immedeately. Queued events must be processed immedeately as soon as the busy interface is marked not busy.
An event client is busy (for a given event type) in at least the following case: While processing an event (of that type).
Cookies are arbitrary objects that can be passed along with a request and are passed back to the client when the event occurs.
An application is designed in the following chronological order and may therefore not have downwards dependencies (except virtual functions):
This design
Libcw interface
Libcw implementation
An application with for each event type:
The event data object
The event server, which owns the event trigger
One or more event generators
One or more event clients
A library would implement everything except the iv. (although example code of an event client should always be provided).
There is one event data class per event type.
There is one event server per event type.
There can be an arbitrary number of event generators per event type.
One event generator can contain an arbitrary number of event triggers of any event type (also more of the same type).
An event client can receive any number of events of any arbitary number of event types. All events of the same type however, enter at the same point.
An event client can own an arbitrary number of busy interfaces.
The event client requests an event type by calling the request() method of the event server. When that event occurs, the event generator passes the event data to the event server, which passes it on to all event clients that requested the event. If a busy interface was passed along with the request, then the event server probes this busy interface to see if the client is busy. If the client is busy, the busy interface queues the event and event data till it is not busy anymore. Otherwise the event is passed directly to the client.