diff --git a/doc/main/reference/assertion_handler.rst b/doc/main/reference/assertion_handler.rst new file mode 100644 index 0000000000..3bfe8fae78 --- /dev/null +++ b/doc/main/reference/assertion_handler.rst @@ -0,0 +1,82 @@ +.. _assertion_handler: + +Custom Assertion Handler +======================== + +.. note:: + The availability of the extension can be checked with the ``TBB_EXT_CUSTOM_ASSERTION_HANDLER`` macro defined in + ``oneapi/tbb/global_control.h`` and ``oneapi/tbb/version.h`` headers. + +.. contents:: + :local: + :depth: 2 + +Description +*********** + +oneTBB implements assertion checking that detects errors in header files and library code. While most assertions are +active in debug builds (controlled by ``TBB_USE_ASSERT``), some assertions remain present in release builds. By +default, failed assertions display an error message and terminate the application. The custom assertion handler +mechanism extends this by allowing developers to implement their own assertion handling functions. The API is +semantically similar to the standard ``std::set_terminate`` and ``std::get_terminate`` functions. + +API +*** + +Header +------ + +.. code:: cpp + + #include + +Synopsis +-------- + +.. code:: cpp + + #define TBB_EXT_CUSTOM_ASSERTION_HANDLER 202510 + + namespace oneapi { + namespace tbb { + namespace ext { + using assertion_handler_type = void(*)(const char* location, int line, + const char* expression, const char* comment); + + assertion_handler_type set_assertion_handler(assertion_handler_type new_handler) noexcept; + + assertion_handler_type get_assertion_handler() noexcept; + }}} + +Types +----- + +.. cpp:type:: assertion_handler_type + +Type alias for the pointer to an assertion handler function. + +Functions +--------- + +.. cpp:function:: assertion_handler_type set_assertion_handler(assertion_handler_type new_handler) noexcept + +Sets the provided assertion handler and returns the previous handler. If ``new_handler`` is ``nullptr``, resets to the +default handler. + +.. note:: ``new_handler`` must not return. If it does, the behavior is undefined. + +.. cpp:function:: assertion_handler_type get_assertion_handler() noexcept + +Returns the current assertion handler. + +Example +******* + +.. literalinclude:: ./examples/assertion_handler.cpp + :language: c++ + :start-after: /*begin_assertion_handler_example*/ + :end-before: /*end_assertion_handler_example*/ + +.. rubric:: See also + +* `Enabling Debugging Features specification `_ diff --git a/doc/main/reference/examples/assertion_handler.cpp b/doc/main/reference/examples/assertion_handler.cpp new file mode 100644 index 0000000000..7eb2bf8ae4 --- /dev/null +++ b/doc/main/reference/examples/assertion_handler.cpp @@ -0,0 +1,53 @@ +/* + Copyright (c) 2025 Intel Corporation + Copyright (c) 2025 UXL Foundation Contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/*begin_assertion_handler_example*/ +#include +#include + +#ifdef TBB_EXT_CUSTOM_ASSERTION_HANDLER + +auto default_handler = tbb::ext::get_assertion_handler(); + +void wrapper_assertion_handler(const char* location, int line, + const char* expression, const char* comment) { + // Execute a custom step before the default handler: log the assertion + std::ofstream log{"example.log", std::ios::app}; + log << "Function: " << location << ", line: " << line << ", assertion " + << expression << " failed: " << comment << "\n"; + log.close(); + + default_handler(location, line, expression, comment); +} + +#endif // TBB_EXT_CUSTOM_ASSERTION_HANDLER + +int main() { +#ifdef TBB_EXT_CUSTOM_ASSERTION_HANDLER + // Set custom handler + tbb::ext::set_assertion_handler(wrapper_assertion_handler); +#endif // TBB_EXT_CUSTOM_ASSERTION_HANDLER + + // Use oneTBB normally - any assertion failures will use custom handler + // ... + +#ifdef TBB_EXT_CUSTOM_ASSERTION_HANDLER + // Restore the default handler + tbb::ext::set_assertion_handler(nullptr); +#endif // TBB_EXT_CUSTOM_ASSERTION_HANDLER +} +/*end_assertion_handler_example*/ diff --git a/doc/main/reference/reference.rst b/doc/main/reference/reference.rst index 20e07ee0a0..2b03f4cb23 100644 --- a/doc/main/reference/reference.rst +++ b/doc/main/reference/reference.rst @@ -18,6 +18,7 @@ It also describes features that are not included in the oneTBB specification. scalable_memory_pools/malloc_replacement_log rvalue_reduce + assertion_handler Preview features ****************