hyperion::assert#

hyperion::assert makes several submodules part of its public interface. See links to their documentation below or scroll further for the primary documentation.

Backtrace

hyperion::assert::backtrace

Runtime Panics

hyperion::assert::panic

Syntax Tokens

hyperion::assert::tokens
- Identifier
- Kind
- Namespace
- Type
- Function
- Variable
- Keyword
- String
- Numeric
- Punctuation
- Error

group assert

Hyperion’s runtime assertions library provides a full-featured set of assertions suitable for most tasks. These assertions have a vastly expanded feature-set compared to the standard assert from #include <cassert>, including:

Detailed Source Location Information: The complete source location where the assertion was triggered is printed, including file, line, column (if available), and enclosing function information.
Expression Decomposition: The full expression passed to the assertion is decomposed into individual sub-expressions, and if the assertion fails, the expression is printed in both its textual form, and with the values of each step in its evaluation rendered in sequence as well. For example, the expression value1 + value2 < 5 might result in the following being printed:
```
Where: value1 + value2 < 5
Evaluated To: (2 + 7) < 5
```
When the result type of a leaf subexpression does not provide a formatting implementation compatible with libfmt, (NotFormattable) is rendered instead.
Backtrace: The backtrace of the callstack up to the point of the triggered assertion is printed, including all available location information: frame number (starting at 0, with 0 being the current frame), address, function name (if available), file name (if available), and line number (if available). Quality of backtrace depends on the target platform and availability of debug symbols/information. Backtrace functionality relies on Boost.Stacktrace and is subject to its support and limitations.
Syntax Highlighting: Full syntax highlighting of the assertion error message, including source locations, expressions, and function names. This uses a simple single-pass implementation for tokenization, and so syntax highlighting is not guaranteed to be 100% accurate (for example, a type may be highlighted as a namespace or vice-versa), but is reasonably accurate for the intended purpose (see screenshots in the README and documentation site for examples of highlighting quality). Syntax highlighting is configurable by making calls to hyperion::assert::highlight::set_color or hyperion::assert::highlight::set_colors at program startup. By default, highlighting uses the foreground colors of the “One Dark” theme.
Context Message Formatting: Assertions take an optional context message, along with optional parameters for the message, using the formatting capabilities of libfmt. The context message must adhere to libfmt’s format string specifications and the additional parameters (if any) must supply a libfmt compatible formatting implementation that is in-scope.
Compiler Optimization Aids: All assertions are implemented in such as way that they inform the compiler that it is extremely unlikely that they will fire, which may aid in code generation and optimization performed by the compiler.

hyperion::assert provides a variety of assertions and assertion-like utilities:

Assumptions (HYPERION_ASSERT_ASSUME): Signals to the compiler that something is assumed to be true. Aids in optimization and code generation. The user must be able to guarantee that the assumption is always valid (otherwise, creates undefined behavior).
Expectations (HYPERION_ASSERT_EXPECT and HYPERION_ASSERT_UNEXPECT): Signals to the compiler that something is expected to be true (or not), but that it is not guaranteed. Aids in optimization and code generation. Similar to the C++20 [[likely]] and [[unlikely]] attributes, but is not required required to be applied on a branch.
Debug Assertions (HYPERION_ASSERT_DEBUG): Typical Debug assertion, but with all of the enhancements mentioned above.
Precondition Assertions (HYPERION_ASSERT_PRECONDITION): Used to verify a precondition has been met at the beginning of a function call. Must be the first statement (or sequence of statements, for multiple preconditions) in the function.
Postcondition Assertions (HYPERION_ASSERT_POSTCONDITION): Used to verify a postcondition has been fulfilled by a function’s operations. May be placed at any point within a function, as long as that location is at the function’s outer-most scope. Checked at scope exit.
Fatal Assertions (HYPERION_ASSERT_FATAL): Used to verify that an irrecoverable error has not occurred.
Requirement Assertions (HYPERION_ASSERT_REQUIRE): Used to verify that a condition that is itself not an error in the state of the program, but otherwise implies that the program can not successfully proceed, has not occurred (examples include Out of Memory or inability to access the network)

All categories except for Assumptions and Expectations provide the feature-set mentioned above.

Example#

auto function() -> int;

auto example() -> void {
    auto value = 2;
    auto some_context = some_call_that_influences_function();

    HYPERION_ASSERT_DEBUG(value + function() == 42,
                          "Example did not equal the meaning of life: {}",
                          some_context);
}

Defines

HYPERION_ASSERT_ASSUME(condition)#

Signals to the compiler that a condition can be safely assumed to be true at all times. Aids in optimization.

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool

Note

Only use this if the condition can be guaranteed to be true. Using this in cases where the condition is not guaranteed results in undefined behavior. If the condition cannot be guaranteed, instead use HYPERION_ASSERT_EXPECT

HYPERION_ASSERT_DEBUG(condition, ...)#

Typical debug assertion. Useful for sanity checking, logic verification, and checking other conditions that you would like to catch early with debug builds, but avoid checking in release.

In Debug builds:

If condition evaluates to false:
- Prints a helpful error message to stderr, including:
  - The source location at which the assertion was triggered
  - The condition expression
  - What condition evaluated to
  - Any additional context you passed in
  - A backtrace of the call stack up to this point
- Triggers a debug break point (to aid in debugging the cause of the assertion)
- Aborts
If condition evaluates to true:
- Does nothing

In Release builds:

This maps to HYPERION_ASSERT_ASSUME, aiding in code generation and optimization

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool
... – A message providing additional context in the case of failure can be included in the error message printed to stderr, followed by any additional arguments to be formatted into that context message. Formatting is performed by libfmt, so the message must follow its format string specification, and arguments must provide a libfmt-compatible formatting implementation.

Note

The core mechanism of Hyperion’s assertions is HYPERION_PANIC. All Hyperion assertions eventually map down to this mechanism in the build mode that corresponds with their traditional assertion strategy being active (For HYPERION_ASSERT_DEBUG that is Debug builds. For most others, that is always). This means that the exact behavior of assertion failures can be customized by registering a custom Panic handler (for example if you don’t want to abort, or don’t want to trigger a break point). The contents of the error message given to HYPERION_PANIC are fixed, however.

HYPERION_ASSERT_PRECONDITION(condition, ...)#

Pre-condition assertion. Useful for verifying that function pre-conditions have been met, prior to performing any actual operations.

If condition evaluates to false:
- Prints a helpful error message to stderr, including:
  - The source location at which the assertion was triggered
  - The condition expression
  - What condition evaluated to
  - Any additional context you passed in
  - A backtrace of the call stack up to this point
- Triggers a debug break point (to aid in debugging the cause of the assertion)
- Aborts
If condition evaluates to true:
- Does nothing

By default, Hyperion’s contract assertions (HYPERION_ASSERT_PRECONDITION and HYPERION_ASSERT_POSTCONDITION) trigger in both Debug and Release builds. If HYPERION_ASSERT_CONTRACT_ASSERTIONS_DEBUG_ONLY has been defined to true, in Release builds this will map to HYPERION_ASSERT_ASSUME, instead.

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool
... – A message providing additional context in the case of failure can be included in the error message printed to stderr, followed by any additional arguments to be formatted into that context message. Formatting is performed by libfmt, so the message must follow its format string specification, and arguments must provide a libfmt-compatible formatting implementation.

Note

HYPERION_ASSERT_POSTCONDITION(condition, ...)#

Post-condition assertion. Useful for verifying that function post-conditions have been met, after performing all operations.

If condition evaluates to false:
- Prints a helpful error message to stderr, including:
  - The source location at which the assertion was triggered
  - The condition expression
  - What condition evaluated to
  - Any additional context you passed in
  - A backtrace of the call stack up to this point
- Triggers a debug break point (to aid in debugging the cause of the assertion)
- Aborts
If condition evaluates to true:
- Does nothing

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool
... – A message providing additional context in the case of failure can be included in the error message printed to stderr, followed by any additional arguments to be formatted into that context message. Formatting is performed by libfmt, so the message must follow its format string specification, and arguments must provide a libfmt-compatible formatting implementation.

Note

HYPERION_ASSERT_REQUIRE(condition, ...)#

General-purpose hard-requirement assertion. Useful for verifying that conditions crucial to program continuation (for example, conditions for which it is not safe and/or possible to continue execution when they are false) have been maintained.

If condition evaluates to false:
- Prints a helpful error message to stderr, including:
  - The source location at which the assertion was triggered
  - The condition expression
  - What condition evaluated to
  - Any additional context you passed in
  - A backtrace of the call stack up to this point
- Triggers a debug break point (to aid in debugging the cause of the assertion)
- Aborts
If condition evaluates to true:
- Does nothing

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool
... – A message providing additional context in the case of failure can be included in the error message printed to stderr, followed by any additional arguments to be formatted into that context message. Formatting is performed by libfmt, so the message must follow its format string specification, and arguments must provide a libfmt-compatible formatting implementation.

Note

HYPERION_ASSERT_FATAL(condition, ...)#

Fatal assertion. Useful for verifying that program-fatal conditions have not occurred.

If condition evaluates to false:
- Prints a helpful error message to stderr, including:
  - The source location at which the assertion was triggered
  - The condition expression
  - What condition evaluated to
  - Any additional context you passed in
  - A backtrace of the call stack up to this point
- Triggers a debug break point (to aid in debugging the cause of the assertion)
- Aborts
If condition evaluates to true:
- Does nothing

Parameters:

condition – The condition to verify. Can be any arbitrary (sequence of) expression(s), as long as the result of that (sequence of) expression(s) is convertible to bool
... – A message providing additional context in the case of failure can be included in the error message printed to stderr, followed by any additional arguments to be formatted into that context message. Formatting is performed by libfmt, so the message must follow its format string specification, and arguments must provide a libfmt-compatible formatting implementation.

Note

HYPERION_ASSERT_EXPECT(expr)#

Marks a condition as expected.

Parameters:

expr – the expected condition

HYPERION_ASSERT_UNEXPECT(expr)#

Marks a condition as unexpected.

Parameters:

expr – the unexpected condition

HYPERION_ASSERT_DEBUG_BREAK()#: Triggers a debugging break point.

group attributes

Hyperion provides several atributes for guiding (or hinting to) the optimizer to better meet the requirements of the user.

Defines

HYPERION_ATTRIBUTE_COLD#: Marks a function as a “cold” code path. “cold” functions are not primed in the instruction cache, branches leading to them are considered “unlikely”, and grouped into a section of the binary away from “hot” functions, to improve locality.

HYPERION_ATTRIBUTE_NO_INLINE#: Marks a function to not be inlined by the optimizer.