4.1 Introduction

Error handling is a large and complex topic with concerns and ramifications that go far beyond language facilities into programming techniques and tools. However, C++ provides a few features to help. The major tool is the type system itself. Instead of painstakingly building up our applications from the built-in types (e.g., char, int, and double) and statements (e.g., if, while, and for), we build types (e.g., string, map, and thread) and algorithms (e.g., sort(), find_if(), and draw_all()) that are appropriate for our applications. Such higher-level constructs simplify our programming, limit our opportunities for mistakes (e.g., you are unlikely to try to apply a tree traversal to a dialog box), and increase the compiler’s chances of catching errors. The majority of C++ language constructs are dedicated to the design and implementation of elegant and efficient abstractions (e.g., user-defined types and algorithms using them). One effect of using such abstractions is that the point where a run-time error can be detected is separated from the point where it can be handled. As programs grow, and especially when libraries are used extensively, standards for handling errors become important. It is a good idea to articulate a strategy for error handling early on in the development of a program.

4.2 Exceptions

Consider again the Vector example. What ought to be done when we try to access an element that is out of range for the vector from §2.3?

• The writer of Vector doesn’t know what the user would like to have done in this case (the writer of Vector typically doesn’t even know in which program the vector will be running).

• The user of Vector cannot consistently detect the problem (if the user could, the out-of-range access wouldn’t happen in the first place).

Assuming that out-of-range access is a kind of error that we want to recover from, the solution is for the Vector implementer to detect the attempted out-of-range access and tell the user about it. The user can then take appropriate action. For example, Vector::operator[]() can detect an attempted out-of-range access and throw an out_of_range exception:

Click here to view code image

double& Vector::operator[](int i)
{
        if (!(0<=i && i<size()))
                throw out_of_range{"Vector::operator[]"};
        return elem[i];
}

The throw transfers control to a handler for exceptions of type out_of_range in some function that directly or indirectly called Vector::operator[](). To do that, the implementation will unwind the function call stack as needed to get back to the context of that caller. That is, the exception handling mechanism will exit scopes and functions as needed to get back to a caller that has expressed interest in handling that kind of exception, invoking destructors (§5.2.2) along the way as needed. For example:

Click here to view code image

void f(Vector& v)
{
        // ...
        try { // out_of_range exceptions thrown in this block are handled by the handler defined below
                compute1(v);                     // might try to access beyond the end of v
                Vector v2 = compute2(v); // might try to access beyond the end of v
                compute3(v2);                    // might try to access beyond the end of v2
        }
        catch (const out_of_range& err) {   // oops: out_of_range error
                // ... handle range error ...
                cerr << err.what() << '
';
        }
        // ...
}

We put code for which we are interested in handling exceptions into a try-block. The calls of compute1(), compute2(), and compute3() are meant to represent code for which it is not simple to determine in advance if a range error will happen. The catch-clause is provided to handle exceptions of type out_of_range. Had f() not been a good place to handle such exceptions, we would not have used a try-block but instead let the exception implicitly pass to f()’s caller.

The out_of_range type is defined in the standard library (in <stdexcept>) and is in fact used by some standard-library container access functions.

I caught the exception by reference to avoid copying and used the what() function to print the error message put into it at the throw-point.

Use of the exception-handling mechanisms can make error handling simpler, more systematic, and more readable. To achieve that, don’t overuse try-statements. In many programs there are typically dozens of function calls between a throw and a function that can reasonably handle the exception thrown. Thus, most functions should simply allow the exception to be propagated up the call stack. The main technique for making error handling simple and systematic (called Resource Acquisition Is Initialization; RAII) is explained in §5.2.2. The basic idea behind RAII is for a constructor to acquire the resources necessary for a class to operate and have the destructor release all resources, thus making resource release guaranteed and implicit.

4.3 Invariants

The use of exceptions to signal out-of-range access is an example of a function checking its argument and refusing to act because a basic assumption, a precondition, didn’t hold. Had we formally specified Vector’s subscript operator, we would have said something like “the index must be in the [0:size()) range,” and that was in fact what we tested in our operator[](). The [a:b) notation specifies a half-open range, meaning that a is part of the range, but b is not. Whenever we define a function, we should consider what its preconditions are and consider whether to test them (§4.4). For most applications it is a good idea to test simple invariants; see also §4.5.

However, operator[]() operates on objects of type Vector and nothing it does makes any sense unless the members of Vector have “reasonable” values. In particular, we did say “elem points to an array of sz doubles” but we only said that in a comment. Such a statement of what is assumed to be true for a class is called a class invariant, or simply an invariant. It is the job of a constructor to establish the invariant for its class (so that the member functions can rely on it) and for the member functions to make sure that the invariant holds when they exit. Unfortunately, our Vector constructor only partially did its job. It properly initialized the Vector members, but it failed to check that the arguments passed to it made sense. Consider:

Vector v(-27);

This is likely to cause chaos.

Here is a more appropriate definition:

Click here to view code image

Vector::Vector(int s)
{
        if (s<0)
                throw length_error{"Vector constructor: negative size"};
        elem = new double[s];
        sz = s;
}

I use the standard-library exception length_error to report a negative number of elements because some standard-library operations use that exception to report problems of this kind. If operator new can’t find memory to allocate, it throws a std::bad_alloc. We can now write:

Click here to view code image

void test(int n)
{
        try {
                Vector v(n);
        }
        catch (std::length_error& err) {
                // ... handle negative size ...
        }
        catch (std::bad_alloc& err) {
                // ... handle memory exhaustion ...
        }
}

void run()
{
        test(-27);                             // throws length_error (-27 is too small)
        test(1 000 000 000);           // may throw bad_alloc
        test(10);                              // likely OK
}

Memory exhaustion occurs if you ask for more memory than the machine offers or if your program already has consumed almost that much and your request pushes it over the limit. Note that modern operating systems typically will give you more space than will fit in physical memory at once, so asking for too much memory can cause serious slowdown long before triggering bad_alloc.

You can define your own classes to be used as exceptions and have them carry as little or as much information as you need from a point where an error is detected to a point where it can be handled (§4.2). It is not necessary to use the standard-library exception hierarchy.

Often, a function has no way of completing its assigned task after an exception is thrown. Then, “handling” an exception means doing some minimal local cleanup and rethrowing the exception. For example:

Click here to view code image

void test(int n)
{
        try {
                Vector v(n);
        }
        catch (std::length_error&) {     // do something and rethrow
                cerr << "test failed: length error
";
                throw;      // rethrow
        }
        catch (std::bad_alloc&) {         // ouch! this program is not designed to handle memory exhaustion
                std::terminate();       // terminate the program
        }
}

In well-designed code try-blocks are rare. Avoid overuse by systematically using the RAII technique (§5.2.2, §6.3).

The notion of invariants is central to the design of classes, and preconditions serve a similar role in the design of functions:

• Formulating invariants helps us to understand precisely what we want.

• Invariants force us to be specific; this gives us a better chance of getting our code correct.

The notion of invariants underlies C++’s notions of resource management supported by constructors (Chapter 5) and destructors (§5.2.2, §15.2.1).

4.4 Error-Handling Alternatives

Error handling is a major issue in all real-world software, so naturally there are a variety of approaches. If an error is detected and it cannot be handled locally in a function, the function must somehow communicate the problem to some caller. Throwing an exception is C++’s most general mechanism for that.

There are languages where exceptions are designed simply to provide an alternate mechanism for returning values. C++ is not such a language: exceptions are designed to be used to report failure to complete a given task. Exceptions are integrated with constructors and destructors to provide a coherent framework for error handling and resource management (§5.2.2, §6.3). Compilers are optimized to make returning a value much cheaper than throwing the same value as an exception.

Throwing an exception is not the only way of reporting an error that cannot be handled locally. A function can indicate that it cannot perform its allotted task by:

• throwing an exception

• somehow returning a value indicating failure

• terminating the program (by invoking a function like terminate(), exit(), or abort() (§16.8)).

We return an error indicator (an “error code”) when:

• A failure is normal and expected. For example, it is quite normal for a request to open a file to fail (maybe there is no file of that name or maybe the file cannot be opened with the permissions requested).

• An immediate caller can reasonably be expected to handle the failure.

• An error happens in one of a set of parallel tasks and we need to know which task failed.

• A system has so little memory that the run-time support for exceptions would crowd out essential functionality.

We throw an exception when:

• An error is so rare that a programmer is likely to forget to check for it. For example, when did you last check the return value of printf()?

• An error cannot be handled by an immediate caller. Instead, the error has to percolate back up the call chain to an “ultimate caller.” For example, it is infeasible to have every function in an application reliably handle every allocation failure and network outage. Repeatedly checking an error-code would be tedious, expensive, and error-prone. The tests for errors and passing error-codes as return values can easily obscure the main logic of a function.

• New kinds of errors can be added in lower-modules of an application so that higher-level modules are not written to cope with such errors. For example, when a previously single-threaded application is modified to use multiple threads or resources are placed remotely to be accessed over a network.

• No suitable return path for errors codes is available. For example, a constructor does not have a return value for a “caller” to check. In particular, constructors may be invoked for several local variables or in a partially constructed complex object so that clean-up based on error codes would be quite complicated. Similarly, an operator doesn’t usually have an obvious return path for error codes. For example, a*b+c/d.

• The return path of a function is made more complicated or more expensive by a need to pass both a value and an error indicator back (e.g., a pair; §15.3.3 ), possibly leading to the use of out-parameters, non-local error-status indicators, or other workarounds.

• The recovery from errors depends on the results of several function calls, leading to the need to maintain local state between calls and complicated control structures.

• The function that found the error was a callback (a function argument), so the immediate caller may not even know what function was called.

• An error implies that some “undo action” is needed (§5.2.2).

We terminate when

• An error is of a kind from which we cannot recover. For example, for many – but not all – systems there is no reasonable way to recover from memory exhaustion.

• The system is one where error-handling is based on restarting a thread, process, or computer whenever a non-trivial error is detected.

One way to ensure termination is to add noexcept (§4.5.3) to a function so that a throw from anywhere in the function’s implementation will turn into a terminate(). Note that there are applications that can’t accept unconditional terminations, so alternatives must be used. A library for general-purpose use should never unconditionally terminate.

Unfortunately, these conditions are not always logically disjoint and easy to apply. The size and complexity of a program matters. Sometimes the tradeoffs change as an application evolves. Experience is required. When in doubt, prefer exceptions because their use scales better and doesn’t require external tools to check that all errors are handled.

Don’t believe that all error codes or all exceptions are bad; there are clear uses for both. Furthermore, do not believe the myth that exception handling is slow; it is often faster than correct handling of complex or rare error conditions, and of repeated tests of error codes.

RAII (§5.2.2, §6.3) is essential for simple and efficient error-handling using exceptions. Code littered with try-blocks often simply reflects the worst aspects of error-handling strategies conceived for error codes.

4.5 Assertions

There is currently no general and standard way of writing optional run-time tests of invariants, preconditions, etc. However, for many large programs, there is a need to support users who want to rely on extensive run-time checks while testing, but then deploy code with minimal checks.

For now, we have to rely on ad hoc mechanisms. There are many such mechanisms. They need to be flexible, general, and imply no cost when not enabled. This implies simplicity of conception and sophistication in implementation. Here is a scheme that I have used:

Click here to view code image

enum class Error_action { ignore, throwing, terminating, logging };                // error-handling alternatives

constexpr Error_action default_Error_action = Error_action::throwing;          // a default

enum class Error_code { range_error, length_error };                                        // individual errors

string error_code_name[] { "range error", "length error" };                               // names of individual errors

template<Error_action action = default_Error_action, class C>
constexpr void expect(C cond, Error_code x) // take "action" if the expected condition "cond" doesn't hold
{
        if constexpr (action == Error_action::logging)
            if (!cond()) std::cerr << "expect() failure: " << int(x) << '' << error_code_name[int(x)] << '
';
        if constexpr (action == Error_action::throwing)
            if (!cond()) throw x;
        if constexpr (action == Error_action::terminating)
            if (!cond()) terminate();
        // or no action
}

This may seem mindboggling at first glance as many of the language features used are not yet presented. However, as required, it is both very flexible and trivial to use. For example:

Click here to view code image

double& Vector::operator[](int i)
{
        expect([i,this] { return 0<=i && i<size(); }, Error_code::range_error);
        return elem[i];
}

This checks if a subscript is in range and takes the default action, throwing an exception, if it is not. The condition expected to hold, 0<=i&&i<size(), is passed to expect() as a lambda, [i,this]{return 0<=i&&i<size();} (§7.3.3). The if constexpr tests are done at compile time (§7.4.3) so at most one run-time test is performed for each call of expect(). Set action to Error_action::ignore and no action is taken and no code is generated for expect().

By setting default_Error_action a user can select an action suitable for a particular deployment of the program, such as terminating or logging. To support logging, a table of error_code_names needs to be defined. The logging information could be improved by using source_location (§16.5).

In many systems, it is important that an assertion mechanism, such as expect(), offers a single point of control of the meaning of assertion failures. Searching a large code base for if-statements that are really checks of assumptions is typically impractical.

void f(const char* p)
{
        assert(p!=nullptr);    // p must not be the nullptr
        // ...
}

static_assert(4<=sizeof(int), "integers are too small");    // check integer size

constexpr double C = 299792.458;                                    // km/s

void f(double speed)
{
        constexpr double local_max = 160.0/(60*60);           // 160 km/h == 160.0/(60*60) km/s

        static_assert(speed<C,"can't go that fast");              // error: speed must be a constant
        static_assert(local_max<C,"can't go that fast");       // OK

        // ...
}

static_assert(4<=sizeof(int));            // use default message

void user(int sz) noexcept
{
        Vector v(sz);
        iota(&v[0],&v[sz],1);           // fill v with 1,2,3,4... (see §17.3)
        // ...
}

4.6 Advice

[1] Throw an exception to indicate that you cannot perform an assigned task; §4.4; [CG: E.2].

[2] Use exceptions for error handling only; §4.4; [CG: E.3].

[3] Failing to open a file or to reach the end of an iteration are expected events and not exceptional; §4.4.

[4] Use error codes when an immediate caller is expected to handle the error; §4.4.

[5] Throw an exception for errors expected to percolate up through many function calls; §4.4.

[6] If in doubt whether to use an exception or an error code, prefer exceptions; §4.4.

[7] Develop an error-handling strategy early in a design; §4.4; [CG: E.12].

[8] Use purpose-designed user-defined types as exceptions (not built-in types); §4.2.

[9] Don’t try to catch every exception in every function; §4.4; [CG: E.7].

[10] You don’t have to use the standard-library exception class hierarchy; §4.3.

[11] Prefer RAII to explicit try-blocks; §4.2, §4.3; [CG: E.6].

[12] Let a constructor establish an invariant, and throw if it cannot; §4.3; [CG: E.5].

[13] Design your error-handling strategy around invariants; §4.3; [CG: E.4].

[14] What can be checked at compile time is usually best checked at compile time; §4.5.2 [CG: P.4] [CG: P.5].

[15] Use an assertion mechanism to provide a single point of control of the meaning of failure; §4.5.

[16] Concepts (§8.2) are compile-time predicates and therefore often useful in assertions; §4.5.2.

[17] If your function may not throw, declare it noexcept; §4.4; [CG: E.12].

[18] Don’t apply noexcept thoughtlessly; §4.5.3.