Custom Assertion Handler

Introduction

In 2021, with the transition from TBB 2020 to the first release of oneTBB, the custom assertion handler feature was removed and has since been requested several times (e.g., https://github.com/uxlfoundation/oneTBB/issues/1258).

OneTBB currently provides assertion functionality for debugging and error reporting purposes through the assertion_failure function. However, applications using oneTBB may have their own error handling, logging, or reporting requirements that differ from the default assertion behavior (which prints to stderr and calls std::abort).

The motivation for this proposal includes:

Improved integration with application error handling: Applications often have sophisticated error handling, logging frameworks, or crash reporting systems that they want to integrate with oneTBB assertions.
Custom recovery mechanisms: Some applications may want to attempt recovery or cleanup operations before terminating, rather than immediately calling std::abort.
Enhanced debugging capabilities: Development environments may want to integrate oneTBB assertions with their debugging tools, IDE breakpoints, or custom diagnostic systems.
Production environment requirements: Production systems may need to log assertion failures to specific locations, send alerts, or perform graceful shutdowns rather than immediate termination.

Currently, when an assertion fails in oneTBB, users have no control over the behavior - the library always prints to stderr and calls std::abort. This rigid behavior can be problematic for applications with specific requirements for error handling and diagnostics.

Proposal

We propose adding a custom assertion handler mechanism that allows applications to set their own assertion handling functions. This proposal is modeled on the assertion handler API that existed in TBB 2020 and is semantically similar to the standard library's std::set_terminate and std::get_terminate functions.

The design parallels both:

Standard Library Pattern: std::set_terminate allows setting a custom termination handler and returns the previous handler, with thread-safe atomic operations for handler storage
TBB 2020 Compatibility: The same assertion_handler_type and set_assertion_handler function signatures that existed in TBB 2020, enabling seamless migration for applications that previously used this functionality

This approach provides both familiarity for developers accustomed to standard library patterns and direct compatibility for applications migrating from TBB 2020 to oneTBB.

New Public API

The proposal adds the following new functions to the public API, using the same signatures as TBB 2020 for compatibility:

Header

cpp

#include <oneapi/tbb/global_control.h>

Syntax

cpp

namespace oneapi {
namespace tbb {
namespace ext {
#if !__TBB_DISABLE_SPEC_EXTENSIONS
    //! Type alias for assertion handler function pointer - same as TBB 2020.
    //! The handler should not return. If it eventually returns, the behavior is runtime-undefined.
    using assertion_handler_type = void(*)(const char* location, int line,
                                           const char* expression, const char* comment);

    //! Set assertion handler and return its previous value.
    //! If new_handler is nullptr, resets to the default handler.
    //! Uses the same signature as TBB 2020 for migration compatibility.
    assertion_handler_type set_assertion_handler(assertion_handler_type new_handler) noexcept;

    //! Return the current assertion handler.
    //! New function not present in TBB 2020, following std::get_terminate pattern.
    assertion_handler_type get_assertion_handler() noexcept;
#endif
}}}

Applications that used the custom assertion handler in TBB 2020 can migrate to this proposal with minimal changes by adding names to namespace tbb:

cpp

namespace tbb {
    using oneapi::tbb::ext::set_assertion_handler;
    using oneapi::tbb::ext::assertion_handler_type;
}

Specification Extension

This API is introduced as an extension to the oneTBB specification, controlled by the __TBB_DISABLE_SPEC_EXTENSIONS macro. By default (macro undefined or defined as 0), the extension will be enabled: set_assertion_handler and get_assertion_handler will be declared and exported, and assertion_failure will dispatch to the active handler. Defining __TBB_DISABLE_SPEC_EXTENSIONS to a non-zero value before including oneTBB headers will disable the extension: these declarations will be excluded from the public API, and the library will always use the default assertion behavior.

The availability of the extension can be checked with the TBB_EXT_CUSTOM_ASSERTION_HANDLER macro after including either the oneapi/tbb/global_control.h or the oneapi/tbb/version.h header. The value of the macro should be increased when observable modifications are made to the feature.

Proposed Implementation Strategy

Core Implementation Approach

The implementation will follow the same patterns used by std::set_terminate and std::get_terminate, while maintaining compatibility with TBB 2020:

Handler Storage: Add a global static atomic variable to store the current assertion handler function pointer, ensuring thread-safe access across the library, similar to how the standard library stores the terminate handler.
Handler Invocation: Modify assertion_failure to call the currently set handler instead of directly executing the default logic, mirroring how std::terminate calls the registered handler.
TBB 2020 Compatibility: Use identical function signatures to ensure existing TBB 2020 code works without modification.

Thread Safety Design

Following the std::set_terminate/std::get_terminate model, the implementation will use atomic operations with appropriate memory ordering (memory_order_acq_rel for exchanges, memory_order_acquire for loads), consistent with standard library implementations. This approach will ensure multiple threads can safely call set_assertion_handler and get_assertion_handler concurrently while guaranteeing that handler changes are visible across all threads without requiring additional synchronization.

The assertion handler is invoked on each assertion failure, even if it happens concurrently in several threads. The default handler uses atomic_do_once to ensure that assertions are reported exactly once per failure. For custom assertion handlers, it is the user's responsibility to ensure that their handler maintains appropriate thread safety if multiple threads might trigger the same assertion simultaneously. This behavior is consistent with TBB 2020, where custom handlers were also responsible for their own thread safety.

The documentation should be extended to provide guidance and examples for implementing thread-safe custom handlers, given that this responsibility shifts to the user. It should also include migration notes for TBB 2020 users, confirming that existing set_assertion_handler calls work unchanged, with identical function signatures and behavior.

Backward Compatibility Preservation

The default assertion handling behavior will remain unchanged, so existing applications will continue to work exactly as before. There will be no changes to existing assertion macros or calling conventions. Applications using custom assertion handlers in TBB 2020 will be able to use the same code with little to no modification, ensuring seamless migration to oneTBB.

Null Handler Protection

Following both the std::set_terminate pattern and TBB 2020 behavior, the implementation will provide protection against null handler pointers. When set_assertion_handler(nullptr) is called, the function will reset to the default handler rather than allowing null dereference. This approach provides a safe way to restore default behavior, similar to how std::set_terminate handles null pointers in the standard library.

TBBBind Integration

To ensure consistent assertion handling across oneTBB components, the TBB shared library will provide the TBBBind shared library with a pointer to the assertion function (which internally calls the active handler). This approach provides unified assertion handling where assertions originating from TBBBind will automatically use the custom assertion handler set by the application, creating a consistent user experience.

This "soft" runtime dependency addition is acceptable, since TBBBind is exclusively used from within the oneTBB shared library. In the unexpected case TBB does not provide the function pointer, the default assertion handler will continue to be used.

No impact on TBBMalloc

TBBMalloc, on the other hand, will not be changed. It will continue to reuse the assertion handling implementation from the core oneTBB library source code yet maintain its own assertion behavior that does not access the oneTBB custom assertion handler. This design preserves TBBMalloc's portability, as it can be used entirely separately from oneTBB and cannot depend on the oneTBB shared library.

Platform Considerations

The implementation will add new set_assertion_handler and get_assertion_handler public entry points to the oneTBB shared library across all supported platforms. We will use function pointers instead of std::function to avoid additional C++ runtime dependencies. Even though std::function provides type safety and supports lambda captures, it also introduces additional complexity and potential performance overhead. Using function pointers maintains ABI stability across different C++ standards and compilers and is consistent with both the standard library approach and the TBB 2020 implementation.

Performance Impact Analysis

The proposed implementation will have minimal performance impact, following the std::set_terminate model:

Normal Execution: No overhead on normal execution paths
Assertion Failure Path: One additional atomic load
Memory Overhead: One atomic pointer per process
Binary Size: Minimal increase due to additional exported functions

Usage Examples

Adding Custom Steps

cpp

auto default_handler = tbb::get_assertion_handler();

void wrapper_assertion_handler(const char* location, int line,
                               const char* expression, const char* comment) {
    // Perform a custom step before calling default handler
    // ... (e.g., log to a file, notify system, custom cleanup, etc.)
    default_handler(location, line, expression, comment);
}

int main() {
    // Set custom handler (identical to TBB 2020 usage)
    tbb::set_assertion_handler(wrapper_assertion_handler);

    // Use oneTBB normally - any assertion failures will use custom handler
    // ...

    // Restore previous handler if needed
    tbb::set_assertion_handler(default_handler);
}

Integration with Logging Framework

cpp

void logging_assertion_handler(const char* location, int line,
                               const char* expression, const char* comment) {
    spdlog::critical("TBB Assertion Failed: {} at {}:{} - {}",
                     expression, location, line, comment ? comment : "");

    // Flush logs before terminating
    spdlog::shutdown();
    std::abort();
}

Development/Testing Handler

cpp

void test_assertion_handler(const char* location, int line,
                            const char* expression, const char* comment) {
    // In testing environments, throw exception instead of aborting
    // to allow test frameworks to catch and handle assertion failures
    std::string msg = std::string("TBB Assertion: ") + expression +
                      " at " + location + ":" + std::to_string(line);
    if (comment) {
        msg += " - " + std::string(comment);
    }
    throw std::runtime_error(msg);
}