LEAF

A function that reports an error:

Checking for errors communicated by a leaf::result<T> works as expected:

The boilerplate if statement can be avoided using BOOST_LEAF_AUTO:

BOOST_LEAF_AUTO can not be used with void results; in that case, to avoid the boilerplate if statement, use BOOST_LEAF_CHECK:

On implementations that define __GNUC__ (e.g. GCC/clang), the BOOST_LEAF_CHECK macro definition takes advantage of GNU C statement expressions. In this case, in addition to its portable usage with result<void>, BOOST_LEAF_CHECK can be used in expressions with non-void result types:

The following is the portable alternative:

Error handling scopes must use a special syntax to indicate that they need to access error objects. The following excerpt attempts several operations and handles errors of type err1:

First, try_handle_some executes the first function passed to it; it attempts to produce a result<U>, but it may fail.

The second lambda is an error handler: it will be called iff the first lambda fails with an error object of type err1. That object is stored on the stack, local to the try_handle_some function (LEAF knows to allocate this storage because we gave it an error handler that takes an err1). Error handlers passed to leaf::try_handle_some can return a valid leaf::result<U> but are allowed to fail.

It is possible for an error handler to declare that it can only handle some specific values of a given error type:

LEAF considers the provided error handlers in order, and calls the first one for which it is able to supply arguments, based on the error objects currently being communicated. Above:

It is possible for an error handler to conditionally leave the failure unhandled:

Any error handler can take an argument of type leaf::error_info const & to get access to generic information about the error being handled; in this case we use the error member function, which returns the unique error_id of the current error; we use it to initialize the returned leaf::result, effectively propagating the current error out of try_handle_some.

If we want to ensure that all possible failures are handled, we use leaf::try_handle_all instead of leaf::try_handle_some:

The leaf::try_handle_all function enforces at compile time that at least one of the supplied error handlers takes no arguments (and therefore is able to handle any failure). In addition, all error handlers are forced to return a valid U, rather than a leaf::result<U>, so that leaf::try_handle_all is guaranteed to succeed, always.

It is of course possible to provide different handlers for different error types:

Error handlers are always considered in order:

The leaf::new_error function can be invoked with multiple error objects, for example to communicate an error code and the relevant file name:

Similarly, error handlers may take multiple error objects as arguments:

Once again, error handlers are considered in order:

An alternative way to write the above is to provide a single error handler that takes the e_file_name argument as a pointer:

An error handler is never dropped for lack of error objects of types which the handler takes as pointers; in this case LEAF simply passes nullptr for these arguments.

Let’s say we have a function parse_line which could fail due to an io_error or a parse_error:

The leaf::on_error function can be used to automatically associate additional error objects with any failure that is "in flight":

Because process_file does not handle errors, it remains neutral to failures, except to attach the current_line if something goes wrong. The object returned by on_error holds a copy of current_line wrapped in struct e_line. If parse_line succeeds, the e_line object is simply discarded; if it fails, the e_line object will be automatically "attached" to the failure.

Such failures can then be handled like so:

The following is equivalent, and perhaps simpler:

What happens if an operation throws an exception? Both try_handle_some and try_handle_all catch exceptions and are able to pass them to any compatible error handler:

Above, we have simply added an error handler that takes a std::bad_alloc, and everything "just works" as expected: LEAF will dispatch error handlers correctly no matter if failures are communicated via leaf::result or by an exception.

Of course, if we use exception handling exclusively, we do not need leaf::result at all. In this case we use leaf::try_catch:

We did not have to change the error handlers! But how does this work? What kind of exceptions does process_file throw?

LEAF enables a novel exception handling technique, which does not require an exception type hierarchy to classify failures and does not carry data in exception objects. Recall that when failures are communicated via leaf::result, we call leaf::new_error in a return statement, passing any number of error objects which are sent directly to the correct error handling scope:

When using exception handling this becomes:

The leaf::throw_exception function handles the passed error objects just like leaf::new_error does, and then throws an object of a type that derives from std::exception. Using this technique, the exception type is not important: leaf::try_catch catches all exceptions, then goes through the usual LEAF error handler selection routine.

If instead we want to use the usual convention of throwing different types to indicate different failures, we simply pass an exception object (that is, an object of a type that derives from std::exception) as the first argument to leaf::throw_exception:

In this case the thrown exception object will be of type that derives from std::runtime_error, rather than from std::exception.

Finally, leaf::on_error "just works" as well. Here is our process_file function rewritten to work with exceptions, rather than return a leaf::result (see Augmenting Errors):

Static type checking creates difficulties in error handling interoperability in any non-trivial project. Using exception handling alleviates this problem somewhat because in that case error types are not burned into function signatures, so errors easily punch through multiple layers of APIs; but this doesn’t help C++ in general because the community is fractured on the issue of exception handling. That debate notwithstanding, the reality is that C++ programs need to handle errors communicated through multiple layers of APIs via a plethora of error codes, result types and exceptions.

LEAF enables application developers to shake error objects out of each individual library’s result type and send them to error handling scopes verbatim. Here is an example:

Later we simply call leaf::try_handle_some, passing an error handler for each type:

A possible complication is that we might not have the option to return leaf::result<int> from f: a third party API may impose a specific signature on it, forcing it to return a library-specific result type. This would be the case when f is intended to be used as a callback:

Can we use LEAF in this case? Actually we can, as long as lib3::result is able to communicate a std::error_code. We just have to let LEAF know, by specializing the is_result_type template:

With this in place, f works as before, even though lib3::result isn’t capable of transporting lib1 errors or lib2 errors:

The object returned by leaf::new_error converts implicitly to std::error_code, using a LEAF-specific error_category, which makes lib3::result compatible with leaf::try_handle_some (and with leaf::try_handle_all):

Ideally, when an error is detected, a program using LEAF would always call new_error, ensuring that each encountered failure is definitely assigned a unique error_id, which then is reliably delivered, by an exception or by a result<T> object, to the appropriate error handling scope.

Alas, this is not always possible.

For example, the error may need to be communicated through uncooperative 3rd-party interfaces. To facilitate this transmission, a error ID may be encoded in a std::error_code. As long as a 3rd-party interface is able to transport a std::error_code, it can be compatible with LEAF.

Further, it is sometimes necessary to communicate errors through an interface that does not even use std::error_code. An example of this is when an external lower-level library throws an exception, which is unlikely to be able to carry an error_id.

To support this tricky use case, LEAF provides the function current_error, which returns the error ID returned by the most recent call (from this thread) to new_error. One possible approach to solving the problem is to use the following logic (implemented by the error_monitor type):

Note that if the above logic is nested (e.g. one function calling another), new_error will be called only by the inner-most function, because that call guarantees that all calling functions will hit the else branch.

For a detailed tutorial see Using error_monitor to Report Arbitrary Errors from C-callbacks.

Recall that error objects communicated to LEAF are stored on the stack, local to the try_handle_same, try_handle_all or try_catch function used to handle errors. To load an error object means to move it into such storage, if available.

Various LEAF functions take a list of error objects to load. As an example, if a function copy_file that takes the name of the input file and the name of the output file as its arguments detects a failure, it could communicate an error code ec, plus the two relevant file names using new_error:

Alternatively, error objects may be loaded using a result<T> that is already communicating an error. This way they become associated with that error, rather than with a new error:

Besides error objects, load can take function arguments:

It is not typical for an error reporting function to be able to supply all of the data needed by a suitable error handling function in order to recover from the failure. For example, a function that reports FILE failures may not have access to the file name, yet an error handling function needs it in order to print a useful error message.

The file name is typically readily available in the call stack leading to the failed FILE operation. Below, while parse_info can’t report the file name, parse_file can and does:

When we invoke on_error, we can pass three kinds of arguments:

For example, if we want to use on_error to capture errno, we could use the e_errno type, which is a simple struct that wraps an int. But, we can’t just pass an e_errno to on_error, because at that time errno hasn’t been set (yet). Instead, we’d pass a function that returns it:

Above, if an exception is thrown, LEAF will invoke the function passed to on_error and associate the returned e_errno object with the exception.

Finally, if on_error is passed a function that takes a single error object by mutable reference, the behavior is similar to how such functions are handled by load; see Loading of Error Objects.

Usually, the compatibility between error handlers and the available error objects is determined based on the type of the arguments they take. When an error handler takes a predicate type as an argument, the handler selection procedure is able to also take into account the value of the available error objects.

Consider this error code enum:

We could handle my_error errors like so:

If a my_error object is available, LEAF will call our error handler. If not, the failure will be forwarded to the caller.

This can be rewritten using the match predicate to organize the different cases in different error handlers. The following is equivalent:

The first argument to the match template generally specifies the type E of the error object e that must be available for the error handler to be considered at all. Typically, the rest of the arguments are values. The error handler is dropped if e does not compare equal to any of them.

In particular, match works great with std::error_code. The following handler is designed to handle ENOENT errors:

This, however, requires C++17 or newer. LEAF provides the following workaround, compatible with C++11:

It is also possible to select a handler based on std::error_category. The following handler will match any std::error_code of the std::generic_category (requires C++17 or newer):

The following predicates are available:

The predicate system is easily extensible, see Predicates.

Consider this snippet:

If we need to attempt a different set of operations yet use the same handlers, we could repeat the same thing with a different function passed as the TryBlock for try_handle_all:

That works, but it is also possible to bind the error handlers in a std::tuple:

The error_handlers tuple can later be used with any error handling function:

Error handling functions accept a std::tuple of error handlers in place of any error handler. The behavior is as if the tuple is unwrapped in-place.

Like exceptions, LEAF error objects are local to a thread. When using concurrency, sometimes we need to collect error objects in one thread, then use them to handle errors in another thread.

LEAF supports this functionality with or without exception handling. In both cases error objects are captured and transported in a leaf::result<T> object.

It is common for an interface to define an enum that lists all possible error codes that the API reports. The benefit of this approach is that the list is complete and usually well documented:

The disadvantage of such flat enums is that they do not support handling of a whole class of failures. Consider the following LEAF error handler:

It will get called if the value of the error_code enum communicated with the failure is one of size_error, read_error or eof_error. In short, the idea is to handle any input error.

But what if later we add support for detecting and reporting a new type of input error, e.g. permissions_error? It is easy to add that to our error_code enum; but now our input error handler won’t recognize this new input error — and we have a bug.

Using exceptions is an improvement because exception types can be organized in a hierarchy in order to classify failures:

In terms of LEAF, our input error exception handler now looks like this:

This is future-proof, but still not ideal, because it is not possible to refine the classification of the failure after the exception object has been thrown.

LEAF supports a novel style of error handling where the classification of failures does not use error code values or exception type hierarchies. Instead of our error_code enum, we could define:

With this in place, we could define a function file_read:

Or, even better:

This technique works just as well if we choose to use exception handling, we just call leaf::throw_exception instead of leaf::new_error:

Now we can write a future-proof handler for any input_error:

Remarkably, because the classification of the failure does not depend on error codes or on exception types, this error handler can be used with try_catch if we use exception handling, or with try_handle_some/try_handle_all if we do not.

It is sometimes necessary to catch exceptions thrown by a lower-level library function, and report the error through different means, to a higher-level library which may not use exception handling.

Suppose we have an exception type hierarchy and a function compute_answer_throws:

We can write a simple wrapper using exception_to_result, which calls compute_answer_throws and switches to result<int> for error handling:

The exception_to_result template takes any number of exception types. All exception types thrown by the passed function are caught, and an attempt is made to convert the exception object to each of the specified types. Each successfully-converted slice of the caught exception object, as well as the return value of std::current_exception, are copied and loaded, and in the end the exception is converted to a result<T> object.

(In our example, error_a and error_b slices as communicated as error objects, but error_c exceptions will still be captured by std::exception_ptr).

Here is a simple function which prints successfully computed answers, forwarding any error (originally reported by throwing an exception) to its caller:

Finally, here is the scope that handles the errors — it will work correctly regardless of whether error_a and error_b objects are thrown as exceptions or not.

Communicating information pertaining to a failure detected in a C callback is tricky, because C callbacks are limited to a specific function signature, which may not use C++ types.

LEAF makes this easy. As an example, we’ll write a program that uses Lua and reports a failure from a C++ function registered as a C callback, called from a Lua program. The failure will be propagated from C++, through the Lua interpreter (written in C), back to the C++ function which called it.

C/C++ functions designed to be invoked from a Lua program must use the following signature:

Arguments are passed on the Lua stack (which is accessible through L). Results too are pushed onto the Lua stack.

First, let’s initialize the Lua interpreter and register a function, do_work, as a C callback available for Lua programs to call:

Next, let’s define our enum used to communicate do_work failures:

We’re now ready to define the do_work callback function:

Now we’ll write the function that calls the Lua interpreter to execute the Lua function call_do_work, which in turn calls do_work. We’ll return result<int>, so that our caller can get the answer in case of success, or an error:

Finally, here is the main function which exercises call_lua, each time handling any failure:

LEAF is able to automatically generate diagnostic messages that include information about all error objects available to error handlers:

The diagnostic_details output for the snippet above tells us that we got an error_code with value 1 (write_error), and an object of type e_file_name with "file.txt" stored in its .value:

To print each error object, LEAF attempts to bind an unqualified call to operator<<, passing a std::ostream and the error object. If that fails, it will also attempt to bind operator<< that takes the .value of the error type. If that also does not compile, the error object value will not appear in diagnostic messages, though LEAF will still print its type.

Even with error types that define a printable .value, the user may still want to overload operator<< for the enclosing struct, e.g.:

The e_errno type above is designed to hold errno values. The defined operator<< overload will automatically include the output from strerror when e_errno values are printed (LEAF defines e_errno in <boost/leaf/common.hpp>, together with other commonly-used error types).

Using diagnostic_details comes at a cost. Normally, when the program attempts to communicate error objects of types which are not used in any error handling scope in the current call stack, they are discarded, which saves cycles. However, if an error handler is provided that takes diagnostic_details argument, such objects are stored on the heap instead of being discarded.

If handling diagnostic_details is considered too costly, use diagnostic_info instead:

In this case, the output may look like this:

Notice how we are missing the Diagnostic details: section. That’s because the e_file_name object was discarded by LEAF, since no error handler needed it.

Instead of the boost::get_error_info API defined by Boost Exception, it is possible to use LEAF error handlers directly. Consider the following use of boost::get_error_info:

We can rewrite g to access my_info using LEAF:

Taking my_info means that the handler will only be selected if the caught exception object carries my_info (which LEAF accesses via boost::get_error_info).

The use of match is also supported:

Above, the handler will be selected if the caught exception object carries my_info with .value() equal to 42.