Custom payloads - Boost.Outcome documentation

# Custom payloads

So far in this tutorial, type `EC` in `result<T, EC>` has always been a `std::error_code` or `boost::system::error_code`. With `NoValuePolicy` set to `default_policy<T, EC, EP>` , `EC` needs in fact to merely satisfy the trait `is_error_code_available<T>` for `EC` to be treated as if an `error_code`. Outcome specialises that trait for `std::error_code` and `boost::system::error_code`, hence they “just work”.

If no specialisation exists, `trait::is_error_code_available<EC>` is true if there exists some ADL discovered free function `make_error_code(EC)`.

Thus, we can in fact use any custom `EC` type we like, including one carrying additional information, or payload. This payload can carry anything you like, and you can tell Outcome to do various things with that payload under various circumstances. For example:

1. If the user tries to observe an unsuccessful `result`, throw a custom exception containing the cause of failure with accompanying context from the payload.
2. If the user ever constructs an `outcome` from a payload carrying `result`, set the exception ptr in the constructed `outcome` to a custom exception containing the cause of the failure with accompanying context from the payload.
3. Transmit a stack backtrace specifying the exact point at which failure occurred, symbolising that backtrace into human readable text at the moment of conversion into human readable text.
4. Upon a namespace-localised `result` from library A being copy/moved into a namespace-localised `result` from C bindings library B, set the C `errno` if the error code and category map onto the `errno` domain.

There are many, many other options of course. This tutorial can only cover a reasonable subset. This section covers Example 1 above, throwing custom exceptions with payload upon observation of an unsuccessful `result`.

Last revised: February 08, 2019 at 22:18:08 UTC