Documentation for Custom Assertion Handler (#1873)

Author: dnmokhov

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 <oneapi/tbb/global_control.h>
+
+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 <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/v1.4-rev-1/elements/onetbb/source/configuration/enabling_debugging_features>`_

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 <oneapi/tbb/global_control.h>
+#include <fstream>
+
+#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*/

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
 ****************