Mu2e Home
Using Exceptions

This page contains some preliminary rough notes about using exceptions and assets in the Mu2e Offline.

The exception handling policy is similar in spirit to that used by CMS, although some technical details differ. The CMS policy can be found at in the CMS guide to managing exceptions.

An important part of the policy is that you should prefer throw over assert in most cases. One critical reason is that, for our production code, the compiler switches are configured to ignore asserts. There is section below with additional information.

  1. Using exceptions
  2. Prefer throw to assert in most cases

Using Exceptions

Mu2e code should only throw exceptions when it intends that art should catch the exception. Mu2e code should not use try/catch blocks to implement normal flow control; this policy should only be violated if one is using a third party product that supports only try/catch for normal flow control.

When Mu2e code throws an exception, the normal syntax is

#include "cetlib/exception.h"
 if ( something_bad ) {
   throw cet::exception("CATEGORY") << "Some useful text.\n";
The string "CATEGORY" is called the category of the exception; it is used by art to decide what action to take in response to the exception. Mu2e will define some standard categories and encourage their use; for now we are making them up as we go along. The text added with operator<< is arbitrary and may be many lines long. Art will decorate the text with information about what module or service was executing at the time of the exception and will add a time stamp. The exception handling code ignores std::endl but not "\n".

In response to an exception art can perform several different actions:

     Rethrow: Shutdown the job as gracefully as possible and terminate the job with non-zero return code.
SkipEvent: Continue processing with the next event.
FailPath: Continue processing with the next path.
FailModule: Continue processing with the next module in the current path
IgnoreCompletely: If possible, continue as if nothing happened.

When an exception is rethrown, art will, if possible, call the appropriate the end* methods for all modules and services. Normally this results in a proper shutdown, with the ROOT output file properly closed, with all event-data files properly closed and with all message streams flushed.

In addition, it is possible to route events that throw exceptions to dedicated output files; one could, for example, configure an output module to write out only events that failed a given path.

When art catches an exception, it consults an run-time-configurable policy for which of the above actions it should take; the policy is stated by saying listing those exeception categories that should Rethrow, those that should SkipEvent and so on. By default almost all categories are configured to rethrow. For a handful of categories, the default is SkipEvent; in particular the "data product not found" exception defaults to SkipEvent.

There are four ways to change the configuration of which exception category has which behaviour:

Why does Mu2e discourage the use of try/catch blocks for normal flow control? Mu2e does not want to pay the run-time costs to establish and tear down the exception handlers; while this would not be a problem if used in appropriate places, the experience of other experiments is that inexperienced programmers quickly adopt the try/catch model and use it in inappropriate places.

Prefer throw to asset in most cases

Mu2e strongly discourages the use of C++ assert to deal with most exceptional circumstances.

  1. Mu2e production code is built using -DNDEBUG, which tells the compiler to ignore asserts. If you intend your test to protect production code, you must use throw.
  2. When an assert is triggered, execution stops immediately, the output streams are not flushed and the ouptut files are not properly closed. In particular, the log file will be incomplete and you will not be able to view the histograms that were filled before the error.
  3. When you throw an exception, art will catch the exception and, by default, will attempt a graceful shutdown. In most cases the graceful shutdown will complete correctly. In these cases the log files will be complete. Also, the histograms, TTrees and other objects in the ROOT root output file will be correct and readable up to the time of the throw. Remember that other people's modules may be running in the same job and that their modules may have useful output, even if your's does not.
  4. When it comes time to write code that will run in the online event filter (AKA the software trigger ) there may be additional guidelines coming from the Trigger/DAQ team.
You should understand that assert is only useful for debug builds. And it should be reserved for situations in which the program is so badly broken that it does not make sense to attempt a graceful shutdown.

Fermilab at Work ]  [ Mu2e Home ]  [ Mu2e @ Work ]  [ Mu2e DocDB ]  [ Mu2e Search ]

For web related questions:
For content related questions:
This file last modified Sunday, 20-Dec-2015 12:57:13 CST
Security, Privacy, Legal Fermi National Accelerator Laboratory