Large software development projects invariably have a need to manage
the distribution and display of state information and state changes.
In other words, they need to manage their software events. Generally,
each such project invents its own way of accomplishing this and then
struggles to get all of its components to play the same way. It is a
difficult process and not always completely successful. This project
helps with that.
AutoEvents completely separates the tasks of supplying the data
needed for a particular event from the methods used to manage the
distribution and display of that event. Consequently, the programmer
writing the code no longer has to worry about that part of the
problem. Likewise the persons responsible for designing the event
management and distribution no longer have to worry about getting
programmers to write conforming code.
It works as follows:
That is the extent of the involvement of the developer of the working code.
Everything else is up to the developer of the event distribution code.
- Each component of a large system is assigned a group name.
All events are associated with one of these groups and are
managed that way. Smaller projects may have only one group, but still.
The programmer determines (in some fashion) that when a certain
point in the code is reached, it is appropriate to create an event.
He then determines what is to be displayed:
- The associated message (formatting string)
- The arguments to the message string, and their types.
- The severity level (a la
- Documentation, supplying an extended description of the meaning of
the event. This should be suitable for use in a separate document.
- A name, compatible with C syntax for variable names.
This event is then described in a stylized comment embedded in the
code (usually where the event is to be emitted), or it may be placed in a
separate event description file. I prefer to embed them in the code.
The programmer then inserts a macro that provides the arguments
to the formatting string, but does not provide
the string itself. The macro name is derived from the event name,
the group name, and the severity of the event. For example, if
an error event in the "foo" group were named "mumbled" and its
associated format string took two arguments, he would insert
something like this in his code:
FOO_ERR_MUMBLED_EVENT( count, string );
The formatting string is not in the macro invocation because
it is known from the event description. In fact, it may not even
be compiled into the program. It may wind up in a separate program
compiled from a internationalized (translated) version.
The source file name and line number can be placed in the argument list
for the dispatch routine. Some compilers can automatically create the
procedure name, too.
A timestamp can be added when the event is recorded.
The dispatch routine can be as simple as `printf()' or as complex as you may wish.
Events can be selected or de-selected by priority threshholds,
sub-group masks or even individual masks. The choice is yours. :-)
String tables can be generated for converting user interface inputs
into these bit masks and priorities.
Events below a certain severity threshhold (e.g., DEBUG) can be compiled out of the code completely.
A centralized dispatch routine could keep track of event frequencies
and throttle them if they come too often.
A centralized dispatch routine could keep track of certain
crucial events and dispatch emails or perform other actions if they
come at all.
Separate event display programs could make independent
decisions about which ones should be displayed.
The documentation strings alluded to above can be extracted
into an event response document that you can rely upon to be complete.
All of these latter issues can be decided upon and re-decided upon
without interfering with the original programmer in any way (other
than, perhaps, a recompile).
This project is not, however, a panacea. Every large scale project
has unique issues that need to be resolved vis-a-vis event management.
It may be necessary, for example, to dump the data into a circular buffer
and return immediately because the comm driver cannot afford to wait
for the formatting and dispatching of the event to complete. What this
project is, though, is a good framework for building a complete,
consistent and well documented solution.
I have a base skeleton that worked for me in getting a couple of
projects started with AutoEvents. If you are interested in helping
to flesh it out and helping me to document how it works, please
email and I will be happy to share it in its current pre-alpha state. :-)