The main idea is that ZOOM modules invoke
(via ZMthrow()
)
code that allows for user intervention,
before or in lieu of
throw
ing a C++ exception,
Key capabilities that extend the C++ exception mechanism include:
try
blocks.
throw
the C++ exception.)
Associations of handlers to exception classes may be altered
dynamically.
These same mechanisms are available for a user to define exceptions associated with non-ZOOM modules.
For a large HEP code,
many users will contribute individual segments,
each intended to fit into some overall framework.
The framework writer(s)
may be expected to pay more attention to specialized software details,
and set things up so as to
free other users to focus on expressing their physics and algorithms.
With that in mind,
the ZOOM exception mechanism makes some assumptions and has several
goals and intentions, briefly summarized as:
The ZOOM Exceptions Package may be obtained
from any of the following sources:
Modules using the mechanism should include the header:
The use, by the framework,
of this package does not force any user to
include anything or change code in any way,
unless that code directly interacts with the exception mechanism
(for example, by checking on exceptions via the history mechanism
or by establishing a handler).
The header file
The same header file defines Each ZOOM facility has an exception tree
starting from the generic exception for the facility
(such as
A mechanism exists for having ZOOM exceptions use the
ErrorLogger
package when outputting information, and to coordinate a user-defined
additional object as an argument to the exception, which can be manipulated
by a handler. This mechanism is the
ZMexAugmented
class. It is part of the ZMtools
package, since it coordinates two other packages which otherwise would
not have cross-dependencies.
Each The default logger, See the header file
ZMexLogger.h
for additional technical details.
User code can independently take advantage of the logging mechanism
to write into the same logs;
if the framework for the job has
specified a different logger for exceptions to use, the user
would need to know its name in order to send information to the same log:
A ZMexception's message
includes the following information:
All Zoom exceptions format information
in a manner consistent with
the
The framework may define ZMexceptions which will use the
ErrorLogger
package when issuing messages. Such exceptions derive from the class
ZMexAugmented
which is in the ZMtools package.
The information logged for an augmented exception is the same as that
output by this logging mechanism, plus a minimal amount conforming to
the ErrorLogger formatting. An advantage is that the ErrorLogger keeps
statistics which can be nicely output.
Overview
try
block.
Framework creators can use this package's tools
to set up behaviors for various exceptions.
throw
ing the exception
via the usual C++ mechanism,
invoking a user-written handler,
or noting but ignoring the exception.
Availability
fsgi02.fnal.gov
)
in directories rooted at
/afs/fnal.gov/files/reports/working-groups/fpcltf/Pkg/Exceptions
#ifndef ZMEXCEPTION_H
#include "Exceptions/ZMexception.h"
#endif
ZMexception.h
is internally code-guarded by defining
ZMEXCEPTION_H
.
All symbols defined there begin with
ZM
;
the exception classes defined by ZOOM modules
all begin with ZMx
(for example, ZMxHepCapture
).
The ZOOM Exception Hierarchy
ZMexception.h
provides a macro, ZMexStandardDefinition
,
to define a ZOOM-style exception class
within a hierarchy of such classes.
ZMexception
,
the root of the tree of ZOOM-style exceptions.
ZMexception
's defaults are provided
in ZMexception.cc
:
ZMexFATAL
,
ZMexThrowErrors
(which ignores exceptions
of severity ZMexWARNING
and below,
but throw
s exceptions of any higher severity), and
ZMexLogAlways
(which by default sends log messages for
all ZMthrow
n exceptions --
even ignored warnings --
to stderr
).
ZMxHepTuple
),
which in turn is derived from ZMexception
.
Using the Exception Mechanism
Three categories of coders
will interact with the ZOOM exception mechanism:
Please also see the companion document,
"Introduction to the Use of Zoom Exceptions."
ZMexception
classes
and make use of the ZOOM exception mechanism
to ZMthrow
them.
The Logging Mechanism
ZMthrow
n ZOOM exception
is recorded via logger objects.
A logger is an instance
of the logger class ZMexLogger
,
constructed with a given behavior,
with respect to one or more log destinations.
ZMlogger
,
has behavior of the class ZMexLogAlways
that, by default, sends information
to stderr
as its destination.
A user or framework writer may, however,
choose to create and/or instantiate other loggers
instead or in addition.
In this way, information generated by ZOOM exceptions
and/or explicit user log calls
can be routed to whatever overall logging mechanism
the experiment chooses to establish.
Such customized loggers
may vary in behavior, destination, or both:
#include "Exceptions/ZMexLogger.h"
ostream myDestination( ... );
// Arbitrary message sink
ZMexLogger myLogger = ZMexLogAlways( myDestination );
// User adaptation (custom destination) of standard behavior
ZMlogger.emit("Any message"); // Send to default logger
myLogger.emit("Any message"); // Send to user-defined logger
An exception handler calls
upon the ZMthrow
n exception object
to furnish a (formatted) message about itself.
In turn, this message is subsequently passed by the handler to the logger.
ZMthrow
ing the exception,
which should uniquely identify
the anomalous circumstance, e.g.,
"Column name too long"
.
murmur
facility,
so that utilities built for parsing and
displaying logs can be applied to ZOOM exception logs as well.