Error Handling & Try<T>
Relevant source files
The following files were used as context for generating this wiki page:
HXLibs implements a unified error handling system that bridges traditional return-code logic with modern C++ exception handling. The system provides a containerized error wrapper, Try<T>, alongside platform-specific utilities for managing Linux system errors and Windows socket errors.
The primary goal is to support asynchronous operations, such as those in a ThreadPool or network server, by allowing exceptions to be captured and deferred until a result is requested by the user.
The Try Container
The Try<T> template acts as a monad-like container that holds either a value of type T or an std::exception_ptr. This structure is essential for propagating errors across thread boundaries or coroutine points where immediate throwing is not feasible.
Container Structure
Try<T> uses a variant-based storage mechanism to ensure it holds exactly one state at a time.
The class diagram shows the internal storage and public interface of the Try container.
Sources: include/HXLibs/container/Try.hpp:26-121
Key Try Operations
| Operation | Description |
|---|---|
operator bool() | Returns true if the container holds a value, false if it holds an exception. |
get() | Returns a reference to the held value. Undefined if holding an exception. |
move() | Moves the held value out of the container. |
rethrow() | Re-throws the captured std::exception_ptr using std::rethrow_exception. |
what() | Safely extracts the error message string from the captured exception. |
Sources: include/HXLibs/container/Try.hpp:60-117
Platform Error Utilities
The library provides specialized tools to handle the disparate error reporting methods of different operating systems.
Linux Error Handling
The LinuxErrorHandlingTools struct manages standard POSIX errors where -1 indicates failure and the reason is stored in errno.
- Expected: A nested template that converts negative integer results into error codes.
- checkError(): Validates a return value; throws
std::system_errorif the value is-1unless specifically excluded via theExcepttemplate parameter. - convertError(): Converts a Linux return value into an
Expected<T>object containing the negativeerrnoon failure. - gaiCategory(): Provides a custom
std::error_categoryforgetaddrinforelated errors.
Sources: include/HXLibs/exception/ErrorHandlingTools.hpp:33-145
Windows Error Handling
Windows utilities focus on Win32 API handles and Socket errors.
- checkWinError(): Checks for null pointers and throws
std::runtime_errorwith the result of::GetLastError(). - checkSocketError(): Specifically handles
SOCKET_ERRORresults.
Sources: include/HXLibs/exception/ErrorHandlingTools.hpp:169-183
Specialized I/O Handling
For io_uring operations, the library uses IoUringErrorHandlingTools::check(int res). Since io_uring returns negative error codes directly, this tool throws std::system_error(-res, std::system_category()) if res < 0.
Sources: include/HXLibs/exception/ErrorHandlingTools.hpp:151-163
Application in Asynchronous Flows
Error handling in HXLibs is heavily integrated into the ThreadPool and database modules.
ThreadPool Integration
When adding tasks to a ThreadPool, results are often handled via thenTry chains. This allows developers to inspect the Try<T> state without necessarily stopping the execution flow.
The flow shows how Try propagates through asynchronous task chains.
Sources: tests/container/03_thread_pool.cpp:81-115
Database Error Management
The DataBaseInterface provides two modes for executing SQL:
- exec(): Directly executes SQL and allows exceptions to propagate normally.
- execNoThrow(): Captures any database exceptions into a
container::Try<>and returns it, preventing immediate stack unwinding.
Sources: include/HXLibs/db/sql/DataBase.hpp:97-123
Exception Modes
The library defines an ExceptionMode enumeration to explicitly toggle between Nothrow and Throw behavior in certain modules.
Sources: include/HXLibs/exception/ExceptionMode.hpp:27-30
Summary
HXLibs provides a robust error handling framework centered on the Try<T> container. By encapsulating both results and exceptions, the library enables consistent error propagation in highly concurrent and asynchronous environments. Platform-specific tools further simplify the transition from low-level OS return codes to high-level C++ exception types.