ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
ALib Module Assert - Programmer's Manual

The ALib assertion system serves as the backbone for runtime validation across various ALib modules. It provides a flexible mechanism for enforcing conditions, outputting diagnostic information, and handling unexpected states during execution of debug-builds of the library.
While primarily intended for internal use, developers working with ALib can also utilize this system in their own code, should they find it suitable for their requirements.

This system is designed to ensure consistency and reliability in debugging and validation across ALib modules. Its modularity allows it to be extended and customized, but it remains lightweight and easy to integrate into existing workflows.

Custom Printability with Conversion Functions
The assertion system includes functionality for converting values into human-readable strings, even for complex or custom types. This is achieved through the type alias alib::assert::AnyConversionFunc, a function pointer that enables conversion of std::any objects to std::string. ALib modules rely on this to display meaningful debug information for internal types. If required, custom conversion functions can be registered using alib::assert::RegisterPrintable, extending this feature to user-defined types.

Assertion Output Format
A predefined format string, alib::assert::FORMAT, governs how assertion messages are structured. The default format, compatible with IDEs such as JetBrains CLion, links messages in the output window to source code locations. It can be customized if you need to adapt the output for specific IDEs.

Stream Management
To segregate error, warning, and informational messages, the system provides dedicated streams: STREAM_ERRORS, STREAM_WARNINGS, and STREAM_MESSAGES. These streams default to std::cerr or std::cout, but can be redirected to custom destinations.

Raising Assertions and Warnings and sending Messages
At the heart of the system lies the templated function Raise, which processes events based on caller information, the message type, and variadic arguments. This central function is responsible for formatting and routing messages to the appropriate output streams.

Custom Assertion Handling
The system includes a mechanism for overriding its default behavior. By setting the function pointer alib::assert::PLUGIN, developers can replace the standard assertion output mechanics with custom one. For example, you could use this feature to integrate assertions with external logging systems or monitoring tools. Module ALox provides such a plugin. Further information is given with the chapter 10.3.4 Logging ALib Assertions of the Programmer's Manual of that module.

Preprocessor Macros
A suite of macros, such as ALIB_ERROR, ALIB_WARNING, or ALIB_ASSERT_ERROR, simplifies the use of the assertion system. These macros encapsulate common assertion patterns, collect the CallerInfo struct, prune the code away with release-compilations, etc. Developers can use these macros directly in their custom code, if they choose to adopt the assertion system.

Conclusion
While primarily intended for internal use, its flexibility allows developers to leverage it for their own projects if desired.

Its features, such as custom printability, configurable output formats, and stream management, make it adaptable to a variety of needs without imposing itself as a mandatory or universal solution.

The ALib assertion system ensures robust runtime validation and debugging capabilities. While designed as an internal utility for ALib modules, the assertion system is flexible enough to be employed in custom projects. Developers can extend its functionality by:

  • registering custom conversion functions for user-defined types,
  • change the output format,
  • redirecting output streams, or
  • using a custom plug-in, for example, to attach custom monitoring

However, this is entirely optional; the primary role of the system is its use within ALib itself.