type 'a t
This is the type of an event system. Such a system is a container for both an event queue and a list of event handlers.
An event handler can either: - accept an event. To signal this the handler just returns normally. - reject an event. The handler rejects an event by raising Reject. This means that all other handlers are gone through and asked whether they want the event or not. - accept an event and terminate itself. The handler is then removed from the list of known handlers. This is signaled by the Terminate exception.
Note that it is impossible to reject an event and terminate.
While running the handler can generate new events and add new handlers to the list of known handlers. New events are simply appended to the event queue. New handlers take effect first when the next event is scheduled (you cannot add a handler and reject an event, hoping that the new handler will get the event). It is possible to both add events and handlers even if the current event is rejected.
Note: There are no precautions taken to make this module thread-safe. As the interface is mainly functional, it is possible to use it in a multi-threaded environment as long as it is avoided that two threads access the same event system.
val create : ('a t -> unit) -> 'a t
create <source>: Makes a new event system with no handlers and no events but with a default event source. The default event source is run if there are no pending events. It can look elsewhere to see if there are new events arriving and put the new events into the queue. If the default source returns without having generated an event the system stops.
val add_event : 'a t -> 'a -> unit
add_event <system> <event>: Puts <event> into the event queue of <system>.
val add_handler : 'a t -> ('a t -> 'a -> unit) -> unit
add_handler <system> <handler>: Adds <handler> to the list of handlers of <system>.
val run : 'a t -> unit
Running a system means that, unless the queue is empty, the events at the time of the 'run' invocation and all later added events are gone through. Each event is presented the handlers until one handler accepts the event. Events rejected by all handlers are dropped silently. If there is no pending event the default event source is called once. If there are still no events the system stops and returns. If there are events to process but no handlers which can do them the exception Out_of_handlers is raised. Note that there is an implicit order among the handlers which is simply the order the handlers have been added to the system. This means that you can set fallback handler which catches any unprocessed event by adding it last. Note that the events are processed in the order they happen. There is no mechanism to assign priorities to events.
NOTE ON EXCEPTIONS:
Handlers are allowed to raise arbitrary exceptions. Exceptions other than Reject and Terminate are not caught, so the caller has to do this if appropriate. It is possible to restart an event system by just calling 'run' again. As the last event has not been handled it is the "next" event.
Go to the first, previous, next, last section, table of contents.