Using Exceptions

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";
 }

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

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:

• The command line switch --rethrow-default will make the default setting for all exceptions be Rethrow.
• An equivalent action can be done in the .fcl file,

  services : {
    scheduler : {
       defaultExceptions : false
    }
  }
  

• ( The information in this bullet has not yet been tested ). One can configure the behaviour on a detailed, category by category basis using a syntax like:

  services : {
    scheduler : {
       defaultExceptions : false
       SkipEvent : [ "CategoryName1", "CategoryName2", "CategoryName3" ]
    }
  }
  
  

  The fcl parameters for the actions are named IgnoreAll, SkipEvent, FailModule, FailPath and Rethrow. (What is the precedence of the .fcl file settings and the --rethrow-default?)
• The command line option --rethrow-all will ingore the settings in the .fcl file and will set all categories to rethrow.

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.

Security, Privacy, Legal