C system error results
In v2.2.11, C Result support went from second tier to first tier status, and
now you can create, query and manipulate a subset of Result types entirely from
within C by including <boost/outcome/experimental/result.h>.
The subset supported are those result<T, E> which are a status_result<T>
i.e. the E is hardcoded to experimental::error which is the type erased runtime
polymorphic holder for any errored status_code whose payload is not bigger
than an intptr_t. This is the most useful subset of Outcome Experimental’s
possible Result types, allowing arbitrary custom error coding schemes from
any unknown source to work seamlessly with all others, including errors from
the system or third party libraries.
The operations available to C are:
BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T)- Declares to C a
status_resulttype uniquely identified byident.Tis available at the member variable.value, andstruct cxx_status_code_systemis available at the member variable.error. If in C++, implements C extern functions for making successful and failure results of this type. If you call this from within C++, make SURE it is not within aextern "C"block! BOOST_OUTCOME_C_RESULT_SYSTEM(ident)- A reference to a previously declared
status_resulttype with uniqueident. BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_SUCCESS(ident, expr)(needs C++ counterpart linked into final binary)- This invokes the aforementioned extern function which creates a
status_resultwith a successful value of typeT. BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_POSIX(ident, expr)(needs C++ counterpart linked into final binary)- This invokes the aforementioned extern function which creates a
status_resultwith a failure of typeposix_coderepresenting a POSIXerrno. BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_SYSTEM(ident, expr)(needs C++ counterpart linked into final binary)- This invokes the aforementioned extern function which creates a
status_resultwith a failure of typeposix_coderepresenting a POSIXerrnoif on POSIX; if on Windows then a failure of typewin32_coderepresenting a Win32 error code from a Windows API.
BOOST_OUTCOME_C_RESULT_HAS_VALUE(r)- Evaluates to 1 (true) if the input
resulthas a value. BOOST_OUTCOME_C_RESULT_HAS_ERROR(r)- Evaluates to 1 (true) if the input
resulthas an error. BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)- Evaluates to 1 (true) if the input
result's error value is a code in the POSIXerrnodomain.
BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(expr)- If the
status_resultreturned byexpris errored, exit the current function returning the result. This obviously requires that the return type of the current function matches that ofexpr. BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(cleanup, expr)- Same as the above, but execute
cleanupjust before exiting the function if returning failure. BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, cleanup, expr)- Same as the above, but set
varequal to the result's.valueon success. BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(var, ident, cleanup, expr)- Same as the above, but use
identas the return type instead. This allows the return type of the calling function to differ from that ofexpr.
BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, uuid, {enum mapping-sequence, ...})- This declares to C an extern function which creates a
status_resultfrom a C enum. If in C++, it implements aquick_status_code_from_enumfor the C enum and the associated extern function, and you will need to supplyuuidand the appropriate enum value mapping sequence as per thequick_status_code_from_enumdocumentation. BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FROM_ENUM(ident, enum_name, expr)(needs C++ counterpart linked into final binary)- This invokes the aforementioned extern function which creates a
status_resultfrom a C enum.
The operations available to C++ are:
BOOST_OUTCOME_C_TO_RESULT_SYSTEM_CODE(ident, status_code<T>)- Returns a previously declared C Result from its matching C++
status_code. NOTE that the destructor of the C++ status code is NOT called. If this is important to your status code, it is 100% on you to ensure that your C Result reenters a C++ Result at the end of its lifetime. to_result(any C Result)- This is an overloaded C++ free function which returns the C++ status_code<T> matching its input C Result.
Using the above you can write C code using Outcome.Experimental’s Result type quite effectively. Let’s look at an example of use next.



