Outcome 2.2 library

Introduction

Outcome is a set of tools for reporting and handling function failures in contexts where directly using C++ exception handling is unsuitable. Such contexts include:

• there are programs, or parts thereof, that are compiled with exceptions disabled;

• there are parts of program that have a lot of branches depending on types of failures, where if-statements are cleaner than try-catch blocks;

• there is a hard requirement that the failure path of execution should not cost more than the successful path of execution;

• there are situations, like in the filesystem library, where whether the failure should be handled remotely (using a C++ exception throw), or locally cannot be made inside the function and needs to be decided by the caller, and in the latter case throwing a C++ exception is not desirable for the aforementioned reasons;

• there are parts of the program/framework that themselves implement exception handling and prefer to not use exceptions to propagate failure reports across threads, tasks, fibers, etc;

• one needs to propagate exceptions through layers that do not implement exception throw safety;

• there is an external requirement (such as a company-wide policy) that failure handling paths are explicitly indicated in the code.

• where interoperation with C code, without having to resort to C++ exception wrapper shims, is important.

• where your mostly C code base needs exception-like error handling, and the subset of Outcome’s functionality available in C is sufficient for your needs.

Outcome addresses failure handling through returning a special type from functions, which is able to store either a successfully computed value (or void), or the information about failure. Outcome also comes with a set of idioms for dealing with such types.

Particular care has been taken to ensure that Outcome has the lowest possible impact on build times, thus making it suitable for use in the global headers of really large codebases. Storage layout is guaranteed and is C-compatible for result<T, E>¹, thus making Outcome based code long term ABI-stable.

Fully deterministic all-noexcept C++ Coroutine support in Outcome is particularly strong, and we supply Outcome-optimising eager<T, Executor = void>/atomic_eager<T, Executor = void> , lazy<T, Executor = void>/atomic_lazy<T, Executor = void> and generator<T, Executor = void> awaitables which work for any user type.

Sample usage (C++)

The main workhorse in the Outcome library is result<T>: it represents either a successfully computed value of type T, or a std::error_code/boost::system::error_code² representing the reason for failure. You use it in the function’s return type:

outcome::result<string> data_from_file(string_view path) noexcept;

It is possible to inspect the state manually:

if (outcome::result<string> rslt = data_from_file("config.cfg"))
  use_string(rslt.value());                   // returns string
else
  throw LibError{rslt.error(), "config.cfg"}; // returns error_code

Or, if this function is called in another function that also returns result<T>, you can use a dedicated control statement:

outcome::result<int> process(const string& content) noexcept;

outcome::result<int> int_from_file(string_view path) noexcept
{
  BOOST_OUTCOME_TRY(auto str, data_from_file(path));
  // if control gets here data_from_file() has succeeded
  return process(str);  // decltype(str) == string
}

BOOST_OUTCOME_TRY is a control statement. If the returned result<T> object contains an error information, the enclosing function is immediately returned with result<U> containing the same failure information; otherwise an automatic object of type T is available in scope.

Sample usage (C)

Equivalent to the C++ API: BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T) declares the C type, thereafter BOOST_OUTCOME_C_RESULT_SYSTEM(ident) refers to it. You use it in the function’s return type:

BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(result_string, const char *)

BOOST_OUTCOME_C_RESULT_SYSTEM(result_string) data_from_file(const char *path);

It is possible to inspect the state manually:

  BOOST_OUTCOME_C_RESULT_SYSTEM(result_string) rslt = data_from_file("config.cfg");
  if(BOOST_OUTCOME_C_RESULT_HAS_VALUE(rslt))
    use_string(rslt.value);  // returns string
  else
    fprintf(stderr, "%s\n", outcome_status_code_message(&rslt.error));

Or, if this function is called in another function that also returns BOOST_OUTCOME_C_RESULT_SYSTEM(ident), you can use a dedicated control statement:

BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(result_int, int)

BOOST_OUTCOME_C_RESULT_SYSTEM(result_int) process(const char *content);

BOOST_OUTCOME_C_RESULT_SYSTEM(result_int) int_from_file(const char *path)
{
  BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(const char *str, result_int, /* cleanup on fail */, data_from_file(path));
  // if control gets here data_from_file() has succeeded
  return process(str);  // decltype(str) == string
}

The C Result is guaranteed to be layout identical to its C++ equivalent. Convenience conversion functions are available, but you can reinterpret cast too.