Chapter 2. The Equeue module

Table of Contents
2.1. Description
2.2. A silly example

2.1. Description

The interface of the Equeue module.

type 'a t              (* Event systems over events of type 'a *)

exception Reject       (* Possible reaction of an event handler *)
exception Terminate    (* Possible reaction of an event handler *)

exception Out_of_handlers     (* Error condition *)

val create      : ('a t -> unit) -> 'a t
val add_event   : 'a t -> 'a -> unit
val add_handler : 'a t -> ('a t -> 'a -> unit) -> unit
val run         : 'a t -> unit

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:

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:

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.