Fermi Physics Class Libraries Internal Module: Exceptions

ZOOM ZOOM

Exceptions -- ZMx

Exceptions and Logging Mechanism

The Zoom exception mechanism is intended:
  1. to provide the tools used internally by ZOOM modules to handle exceptions, and
  2. to provide the user with interfaces to control how to react to problems.

The main idea is that ZOOM modules invoke (via ZMthrow()) code that allows for user intervention, before or in lieu of throwing a C++ exception,

Key capabilities that extend the C++ exception mechanism include:

These same mechanisms are available for a user to define exceptions associated with non-ZOOM modules.


Overview
Using the Exception Mechanism
The Logging Mechanism
Physical Structure
Augmented Exceptions and the ErrorLogger package.

Overview

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:


Availability

The ZOOM Exceptions Package may be obtained from any of the following sources:

Modules using the mechanism should include the header:

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 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 ZOOM Exception Hierarchy

The header file ZMexception.h provides a macro, ZMexStandardDefinition, to define a ZOOM-style exception class within a hierarchy of such classes.

The same header file defines ZMexception, the root of the tree of ZOOM-style exceptions. ZMexception's defaults are provided in ZMexception.cc:

Each ZOOM facility has an exception tree starting from the generic exception for the facility (such as ZMxHepTuple), which in turn is derived from ZMexception.

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.

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

The Logging Mechanism

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

The default logger, 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

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:

ZMlogger.emit("Any message"); // Send to default logger
myLogger.emit("Any message"); // Send to user-defined logger
An exception handler calls upon the ZMthrown exception object to furnish a (formatted) message about itself. In turn, this message is subsequently passed by the handler to the logger.

A ZMexception's message includes the following information:

All Zoom exceptions format information in a manner consistent with the murmur facility, so that utilities built for parsing and displaying logs can be applied to ZOOM exception logs as well.


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.

Physical Structure

  1. Declaring & defining exceptions:

  2. Instantiating & throwing exceptions:

  3. Handlers:

  4. Loggers:

  5. History of thrown exceptions:

ZOOM Home Page - Fermilab at Work - Fermilab Home


Mark Fischler, Philippe Canal, and Walter Brown
Last modified: March 4, 2000