Error Handling

⚠️ This page is not final and not decided or agreed upon. It is in draft form for if we decide to move forward with this strategy.

TL;DR

• For recoverable errors, return a VW::result<T> from the function
  • This should be used in 99% of cases
  • Always decorate with [[nodiscard]] to avoid accidentally not checking
• For unrecoverable errors, use VW_THROW (which can be customized for noexcept environments)
  • In our codebase, this means out of memory errors and programming bugs

---

Error Handling in VW

Starting in VW 10, there is a new error handling system. The system is very similar to how Rust handles errors.

The most important type is VW::result<T> which is a type alias for tl::expected<T, VW::error>. This type is used to return either a value or an error. For functions with no return value, VW::result<void> is used.

The VW::error type contains an error code enum and an error message. The error code enum is used to determine the type of error that occurred. The error message is a string that contains more information about the error.

Therefore, for all functions which can fail VW::result<T> should be used. All functions which return VW::result<T> should be marked with [[nodiscard]] to ensure that the error is checked.

However, for situations which a failure indicates a programming bug and not an error that should be recoverable. VW_THROW should be used, which will by default throw an exception. There are a few different defines that can be used to control the behavior of VW_THROW (only 1 should be defined at a time):

• VW_NOEXCEPT - If this is defined, then VW_THROW will print a diagnostic and call std::abort instead of throwing an exception.
• VW_NOEXCEPT_IGNORE - If this is defined, then VW_THROW will just print a diagnostic. This is not recommended and will result in undefined behavior after the first time VW_THROW is called.
• VW_NOEXCEPT_IGNORE_SILENT - If this is defined, then VW_THROW will do nothing at all. This is not recommended and will result in undefined behavior after the first time VW_THROW is called.

Failure to allocate memory is handled with the above VW_THROW semantics and std::bad_alloc.

Therefore, a consumer of VowpalWabbit could decide to catch these very few exceptions and handle them in a way that is appropriate for their application. But in general, these represent programming bugs and should be fixed or unrecoverable errors.

Using VW::result<T>

To return the expected value, simply return the value:

VW::result<int> foo() { return 5; }

To return success in a void function:

VW::result<void> foo() { return {}; }

To return a generic error, use VW::make_error:

VW::result<int> foo() { return VW::make_error("Function failed."); }

To return a specific error code:

VW::result<int> foo() { return VW::make_error(VW::error_code::IO, "File operation failed."); }

To check if the result is an error or value, use VW::result<T>::has_value(). It is also convertible to a bool. Because VW::result<T> follows value semantics there are many ways to properly handle and use the type.

auto result = foo();
if (result) { std::cout << "Success! Value is: " << *result; }
else { return result; }

// or
ASSIGN_OR_RETURN(result, foo());
std::cout << "Success! Value is: " << *result;

// or
auto result = foo().map([](int value) { std::cout << "Success! Value is: " << value; });
if (!result) { return result; }

Light errors

There is a compile feature called LIGHT_ERRORS which, when enabled, will make the error type only contain an error code enum. This is useful for when you don't need the error message. This is disabled by default. When enabled, rich and dynamic error messages are not available.

This turns VW::error into a trivially copyable type which may be useful for performance. However, it is unclear if this actually helps. Please benchmark and compare if you are interested in using this feature.

Testing

test_common exposes matchers to make writing tests for VW::result easy.

#include "vw/test_common/matchers.h"

[[nodiscard]] VW::result<void> foo();
[[nodiscard]] VW::result<int> bar();

TEST(testsuite, test) {
  // EXPECT_OK is a matcher that checks if the result contains a value (even void)
  EXPECT_OK(foo());

  // This is equivalent to:
  EXPECT_THAT(foo(), HasValue());

  // HasValueAndHolds is a matcher that checks if the result contains a value and that the value matches the given value
  EXPECT_THAT(bar(), HasValueAndHolds(13));

  // HasErrorCode is a matcher that checks an operation failed with a specific error code
  EXPECT_THAT(foo(), HasErrorCode(VW::error_code::GENERIC));
}

Error domains

VW::error is actually a typedef of VW::details::error_impl<VW::error_code>. Therefore, VW::error_code is the error domain, and in VW this is the default domain. Most of the type in library code this is what should be used and for vw_core's API this should be the error domain exposed via the interface.

However, for libraries such as the explore library it is helpful to have a custom error domain. This aids in separating the list of all possible error codes that have to be reasoned over for a given error.

The types used in the explore lib are:

using error = ::VW::details::error_impl<VW::explore::explore_error_code>;

template <typename T>
using result = ::VW::expected<T, VW::explore::error>;

VW::make_error will automatically use the correct error type if any error code enum is passed. If only a string is passed to VW::make_error then it will return the default VW::error.

If crossing the boundary between two error domains then the types need to be mapped to each other. This can be done conveniently with map_error.