-
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.