---

C++ Event Handling Template Library Documentation

0.9b

Overview

This module provides a small set of classes that support the easy generation of, and reaction to, events within a program. Each event type carries data appropriate for its type. This library makes it unnecessary to propagate data via void pointers and makes clearer to the programmer where data is sent from and where data is used. The event generator and event receiver (listener) need not refer to each other, need not know whether the other exists, and need not know each other's type (class). The listener need not know whether data will ever be generated and the generator need not know whether the event will be received by any listener.

So what are situations where you could use such a pattern? Whenever you are faced with a design that requires a "sort of" observer pattern, but where the observer and observable satisfy the above listener-generator description, you need the event-handling pattern instead. An abstract example: a program that can read text commands from a socket could use events to send the data to whoever may be interested in the command. A concrete example:

A stock market program has several components that "live" while the program is running, e.g. a StockMarket object, several Broker objects, several Investor objects, a CentralComputer object, etc. The program runs a loop in which each object is updated every time through the loop to model the stock market according to investor actions. These actions are received on a socket port as an integer id and text string. The id tells the program what type of text command is the string (see below). Additionally, the StockMarket, Broker, and CentralComputer objects can be configured at run time to print out extra debugging info, to take several actions independent of the investor actions, for instance shutdown, crash, etc, or to change operation mode, such as novice vs expert mode. The program reads the text string from a socket port, and depending on the type id of the string (debug type, investor instruction, command, and user level) an event of the appropriate type is created, with the text string in it, and sent. All objects in the system that have registered as listeners of that type of event will hear the event, and take action depending on the text command in it.

Installation

Installation is limited to copying the files in the include subdirectory over to a directory of your choice (or leave them where they are and add that subdirectory to your header search path during compilation). There is no library to build as all files are templates.

Testing

If you want to quickly test whether this library can be used on your development platform, the tests subdirectory contains a test file that tests the event handling framework (and may give you an example of how to use it, though the instructions below are probably clearer).

• GNU g++ platform (Linux, cygwin, Irix, etc): Just type make to build it then ./testListening to run it;
• Other Unix but non-GNU platform: edit makefile for your compiler/OS, then follow the instructions above for GNU;
• VC++: compile tests/testListening.cc then, from a command window, run the executable.

Note that tests/testListening uses assertions but also produces text output. Compare your output to that saved in tests/testOutput.txt. If DEBUG_LEVEL was not changed in include/EventSender.cc, the outputs should match exactly. Note also that the test shows a message with the word "BUG" in it: this is the desired message and does NOT mean that there is a bug in the library. On the contrary, it means that the library is working as expected.

How to use: simple

Using this module is extremely simple:

1. Create your event type by creating a struct/class
2. Make one of your classes a listener of that type of event by inheriting from Listener< YourEvent>
3. Add a call to your listener class' listenForEvents() method
4. Generate an event by calling EventSender< YourEvent >::send( yourEventInstance )

That's it!!! This overview of how the different classes interact may help too.

How to use: advanced

Refer to the class documentation for more details on the following:

1. You can additionally derive your event from PolymorphEvent to make it polymorphic. This will allow you to store various types of event in one container, e.g. for queueing;
2. You can add your own time-stamping functionality whichever way you want, or derive your event struct from TimeStampedEvent<Stamper> to get time-stamping capabilities defined by your Stamper template parameter;
3. Each listener can signify to the generator that the event heard is going to be ignored;
4. There is some protection against infinite loops of event generation via the RecursiveSendError exception;
5. You are in charge of locking and unlocking access to the class methods of EventSender and Listener if multi-threading is used; this will keep performance optimum in single-threaded processes, currently still the most common (note that single-threaded processes does not imply non-parallel; see for instance literature on communicating sequential processes). If you know how to make CEHTL thread safe without incurring the cost of mutexes in single-threaded environments, send me an email (see the admin section below);

Download it

Download the library from SourceForge

Acknowledgements

This library is based on one developed by the author at the National Research Council (NRC) Canada. It is made available open source, with NRC's permission, in the form of CEHTL. This is a completely new design and implementation of the functionality found in the original source for a large, real-time simulator developed at the Integrated Manufacturing Technologies Institute, one of the many branches of NRC.

Admin details

Todo:

Double-check that tests now build with VC++

Should the lib be in its own namespace? It's barely large enough to justify it.

Since:

Sep 2002

Author:

Oliver Schoenborn

This project's CVS repository, located on SourceForge, can be checked out online, or through anonymous (pserver) CVS with the following CVS commands (replace cvshost with cvs.cehtl.sourceforge.net, and when prompted for a password for anonymous, simply press the Enter key):

cvs -d:pserver:anonymous@cvshost:/cvsroot/cehtl login
cvs -z3 -d:pserver:anonymous@cvshost:/cvsroot/cehtl co cehtl

Updates from within the module's directory do not need the -d parameter.

Copyright:

Copyright (C) 2002, 2003 Oliver Schoenborn

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

You can redistribute it and/or modify it under the terms found in the LICENSE file that is included in the library distribution.

---