Introductory manual for the Dispatcher subsystem

All classes that are part of the Dispatcher subsystem are in the strmod::unievent namespace.

Overview

What the heck's a Dispatcher?

A Dispatcher is an interface class the provides simple event dispatching capabilities. It has methods (that subclasses must implement) to allow you to add events to its queue, and methods that cause it to 'fire' one or more of these events.

What's an Event?

An Event is the object that the Dispatcher holds in a queue and 'fires' by calling its TriggerEvent method. It behaves a little like a function pointer that's pointing at a function that takes as an argument the dispatcher that fired the event. Events are supposed to be re-used, and not created individually for each event. That's why they inherit from strmod::lcore::ReferenceCounting and have the EventPtr type.

Why would I use an implementation of Dispatcher?

This is a complicated question. The short answer is that you'd use it when you need to use events to communicate between different parts of your program.

Of course, this begs the question of why you'd use events instead of simple function call, so here are a list of reasons:

  • The function you're calling may do something to the object you're calling it from that's hard to deal with. (i.e. In the place where the call would normally be made, your class invariant might be false.)
  • You may not want the function call to be carried out right away, in order to give other things a chance to do stuff.
  • The function you want to call may be part of an object that logically belongs in a different thread, and you want the call to occur in the control flow of that thread to avoid locking issues.
  • You may not have any good way of knowing, when you write your class, which function you need to call on which object. You can use an event as sort of a function pointer that will be queued up to be called whenever you need to call your function. The new Java AWT and Swing frameworks, for example, turn a GUI button press into an event.

So, what's this got to do with the StreamModule sytem?

There are a few ways in which the Dispatcher subsystem is used in the StreamModule system.

  • The UNIXPollManager uses events to notify interested parties about the state of file descriptors.
  • The SimpleMultiplexer uses events to give other things a chance to run. This is so one stream can't hog the many-to-one direction of the multiplexer.
  • The StreamFDModule will be changed to use events to notify interested parties about error conditions.
  • When signal handling is finished, the signal handler will use events to fold signals back into the normal flow of control.
  • When multi-threading is supported, and the InterThreadModule is done, the InterThreadModule will use events to notify itself (in the proper thread context) about items on the queue.
  • Modules that need to destroy themselves (or the modules they communicate with) will post an event, and the event will do the destruction in order to avoid having this pointers on the stack that point to a dead object.