Fermi Physics Class Libraries Module: EL Graded Asserts

ZOOM ZOOM

Graded Assertions Logging to ErrorLogger

The ErrorLogger package provides a header ErrorLogger/ELassertN.h, that defines macros such as ELassert3(condition) and ELwarningAssert2(condition). These behave like the assert macro but permit gradations of activation, and also route the output (when triggered) to errlog, either with severity ELabort or severity ELwarning.


Purpose and Rationale
Using Graded Asserts Connecting to the ErrorLogger: ELassertN.h

Purpose and Rationale

The granularity of the C assert mechanism is inadequate for some purposes. Every assert() macro is active unless NDEBUG is not defined, and disappears if NDEBUG is defined. For some assertions this is appropriate. However, the coder may well know that some specific assertions are unlikely to become time critical, and ought to remain active even though some degree of optimization has been specified.

The mechanism we use to address this obeys the following rules:

  1. The standard assert mechanism, activated by lack of NDEBUG, continues to behave as in the standard manner, except for a different mode of aborting when an ELassert assertion fails.
  2. When an ELassert fails, instead of writing to cerr and calling exit(), it will issue a message to errlog, of severity ELabort, containing the text of the assertion and the file and line of the failed assertion.
  3. There are several new assert-like macros, such as ELassert1. If any of these are triggered, the behavior is the same as when an ELassert is triggered.
  4. The activation of the new assert-like macros is again controlled by defines. The gradations of asserts will be reflected in the gradations of available defines; for example ELassert1 is de-activated if NDEBUG, NDEBUG1, or NDEBUG2 is defined.
  5. The new assert-like macros, in the case where they are not activated, preprocess down to no code at all ,so that there is no question of removing them "just in case the optimizer isn't that good."
The new graded asserts are more readily deactivated than ordinary asserts, so an experiment can easily leave intact all asserts except those explicitly noted as being time-critical. However, another macro ELsanityCheck(condition) is also provided; this is not deactivated by NDEBUG.

A discussion of the reasoning behind this is available.

There is also a mechanism for declaring assertions that only generate warnings if triggered, allowing a framework wants to continue processing in some manner despite a failed (user) assertion. These are analogous to the corresponding ELasserts but with names like ELwarningAssert1.

Using Graded Asserts Connecting to the ErrorLogger: ELassertN.h

To use the graded asserts that route messages to an error logger, you must have error logging set up.
Specifically, in the scope where the ELassert will appear, there must be an ErrorLog variable named errlog. Also, the file ErrorLogger/ELassertN.h must be included.

Having included ErrorLogger/ELassertN.h, one can use the following macros with the same semantics as assert():

The macros are controlled by symbols as follows:

ErrorLogger/ELassertN.h may be included multiple times in the same code unit. Just like assert.h, it is not code-guarded; thus one can alter the defined-status of the various NDEBUG symbols to modify the activation status of ELassert statements in a given section of code.

An example code snippet:

If one of these macros is triggered, an error message is issued, with severity ELabort. This recommends that the program exit after outputting the error information. (The framework may be set up so as to ignore that recommendation.)

Assertions Issuing Warnings

There are alternative macros, corresponding to each of the above, which differ only in that any error message issued will be assigned severity ELwarning.

ErrorLogger Main Documentation - ZOOM Home Page

Fermilab at Work - Fermilab Home


Mark Fischler
Last modified: May 11, 2000.