Chapter 2. The Equeue module

Table of Contents
2.1. Description
2.2. A silly example

2.1. Description

The values of type Equeue.t are called event systems, and contain:

The module is intended to be used as follows: First, an event system is created, and initialized with an event source. Some event handlers are added:

let some_source esys = ... in

let handler1 esys e = ... in
let handler2 esys e = ... in
... (* more handlers *)

let esys = Equeue.create some_source in
Equeue.add_handler esys handler1;
Equeue.add_handler esys handler2;
... (* more handlers *)
It is necessary that at least one handler is added. In the second step, the event system can be started:
Equeue.run esys
This means the following:

  • At the beginning, the function realizing the event source is called once. The function has the chance to add the first event(s) to the event queue by calling Equeue.add_event.

  • If the event queue is not empty: It is iterated over all events currently in the queue. Every event is tried to be delivered to a handler by the simplest possible algorithm: The handlers are tried in turn, and the first handler that wants to consume the event gets the event.

  • After one round of iteration over all events, it is possible that the handlers did already add further events to the queue, or it is possible that the queue is now empty. In the first case, the iteration is simply repeated with the newly added events. In the second case, the event source is called. If there are now events, they are iterated.

  • Otherwise, the event system terminates.

A handler can indicate either that it wants to consume the event, or that it rejects the event, or that it wants to be removed from the list of handlers. Consumption is indicated by returning normally. Rejection is indicated by raising the Equeue.Reject exception. If the handler raises the Equeue.Terminate exception, the event is consumed and the handler is removed from the list of handlers.

Other exceptions, either raised within the event source function or within a handler function, simply fall through the event loop; they are not caught. However, the event system is restartable, which means:

  • If the exception happened within the event source, the source is called again.

  • If the exception happened within a handler function, the current event is scheduled again.

The event source is called when there are no events in the equeue. Note that the event source may not only add events, but also event handlers. It is an error if after the invocation of the event source there are events in the queue, but no handlers are defined. In this case, the exception Out_of_handlers is raised.