Fermi Physics Class Libraries Module: Graded Asserts

ZOOM ZOOM

Graded Assertions Mini-package

Graded Asserts

This mini-package provides a header ZMtools/assertN.h, that defines macros such as assert2(condition). These behave like the assert macro but permit gradations of activation so that some set of asserts can remain active while others disappear for optimization purposes.

Graded Asserts Connecting to ErrorLogger

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

These packages may be obtained from the following sources:


Purpose and Rationale
Using Graded Asserts: assertN.h
Using 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.
  2. There are several new assert-like macros, such as assert1. If any of these are triggered, the behavior is the same as when an assert is triggered.
  3. 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.
  4. 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 easliy leave intact all asserts except those explicitly noted as being time-critical. However, another macro sanityCheck(condition) is also provided; this is not deactivated by NDEBUG.

A discussion of the reasoning behind this is available.

We also provide a way to have assertion-failures channeled through the ErrorLogger mechanism if that is in use. This lets such messages be routed to the designated destinations which the experiment will be accustomed to perusing.

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.

  1. The ELasserts have the same semantics as the graded asserts discussed above.
  2. When an ELassert is triggered, it routes to errlog an error message of severity ELabort, containing the text and the file and line of the failed assertion.
  3. The activation of the ELassert macros is controlled by the same defines as would control the gradations of ordinary assertions and sanity checks.
  4. The ELassert macros, in the case where they are not activated, preprocess down to no code at all.
  5. A separate set of macros provide precisely the same behavior as the ELasserts, except that the error messages they issue if triggered have severity ELwarning.

Using Graded Asserts: assertN.h

To use the graded asserts, include the file assertN.h. Then use the following macros with the same semantics as assert(): These are controlled by several defines: An example code snippet:

Note that unless coders start employing the new graded forms of assert, the granularity will of course remain either all asserts active, or none.

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

Then the following macros may be used, with the same semantics as the corresponding graded asserts:

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.

ZOOM Home Page - Fermilab at Work - Fermilab Home


Mark Fischler
Last modified: May 11, 2000.