Implement a throwing version of _LIBCPP_ASSERT.
This patch implements changes to allow _LIBCPP_ASSERT to throw on failure
instead of aborting. The main changes needed to do this are:
1. Change _LIBCPP_ASSERT to call a handler via a replacable function pointer
instead of calling abort directly. Additionally this patch implements two
handler functions, one which aborts and another that throws an exception.
2. Add _NOEXCEPT_DEBUG macro for disabling noexcept spec on function which
contain _LIBCPP_ASSERT. This is required in order to prevent assertion
failures throwing through a noexcept function. This macro has no effect
unless _LIBCPP_DEBUG_USE_EXCEPTIONS is defined.
Having a non-aborting _LIBCPP_ASSERT is very important to allow sane testing of
debug mode. Currently we can only have one test case per file, since the test
case will cause the program to abort. Testing debug mode this way would require
thousands of test files, most of which would be 95% boiler plate. I don't think
this is a feasible strategy. Fortunately using a throwing debug handler solves
these issues.
Additionally this patch rewrites the documentation for debug mode.
git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@290651 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/DesignDocs/DebugMode.rst b/docs/DesignDocs/DebugMode.rst
new file mode 100644
index 0000000..166c733
--- /dev/null
+++ b/docs/DesignDocs/DebugMode.rst
@@ -0,0 +1,100 @@
+==========
+Debug Mode
+==========
+
+.. contents::
+ :local
+
+.. _using-debug-mode:
+
+Using Debug Mode
+================
+
+Libc++ provides a debug mode that enables assertions meant to detect incorrect
+usage of the standard library. By default these assertions are disabled but
+they can be enabled using the ``_LIBCPP_DEBUG`` macro.
+
+**_LIBCPP_DEBUG** Macro
+-----------------------
+
+**_LIBCPP_DEBUG**:
+ This macro is used to enable assertions and iterator debugging checks within
+ libc++. By default it is undefined.
+
+ **Values**: ``0``, ``1``
+
+ Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
+ assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
+ which provides additional assertions about the validity of iterators used by
+ the program.
+
+ Note that this option has no effect on libc++'s ABI
+
+**_LIBCPP_DEBUG_USE_EXCEPTIONS**:
+ When this macro is defined ``_LIBCPP_ASSERT`` failures throw
+ ``__libcpp_debug_exception`` instead of aborting. Additionally this macro
+ disables exception specifications on functions containing ``_LIBCPP_ASSERT``
+ checks. This allows assertion failures to correctly throw through these
+ functions.
+
+Handling Assertion Failures
+---------------------------
+
+When a debug assertion fails the assertion handler is called via the
+``std::__libcpp_debug_function`` function pointer. It is possible to override
+this function pointer using a different handler function. Libc++ provides two
+different assertion handlers, the default handler
+``std::__libcpp_abort_debug_handler`` which aborts the program, and
+``std::__libcpp_throw_debug_handler`` which throws an instance of
+``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing
+assertion handler as follows:
+
+.. code-block:: cpp
+
+ #define _LIBCPP_DEBUG 1
+ #include <string>
+ int main() {
+ std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
+ try {
+ std::string::iterator bad_it;
+ std::string str("hello world");
+ str.insert(bad_it, '!'); // causes debug assertion
+ } catch (std::__libcpp_debug_exception const&) {
+ return EXIT_SUCCESS;
+ }
+ return EXIT_FAILURE;
+ }
+
+Debug Mode Checks
+=================
+
+Libc++'s debug mode offers two levels of checking. The first enables various
+precondition checks throughout libc++. The second additionally enables
+"iterator debugging" which checks the validity of iterators used by the program.
+
+Basic Checks
+============
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
+
+The following checks are enabled by ``_LIBCPP_DEBUG``:
+
+ * FIXME: Update this list
+
+Iterator Debugging Checks
+=========================
+
+These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
+
+The following containers and STL classes support iterator debugging:
+
+ * ``std::string``
+ * ``std::vector<T>`` (``T != bool``)
+ * ``std::list``
+ * ``std::unordered_map``
+ * ``std::unordered_multimap``
+ * ``std::unordered_set``
+ * ``std::unordered_multiset``
+
+The remaining containers do not currently support iterator debugging.
+Patches welcome.
diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index d6d1095..de87c9c 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -133,17 +133,7 @@
thread safety annotations.
**_LIBCPP_DEBUG**:
- This macro is used to enable assertions and other debugging checks within
- libc++. All debugging checks are disabled by default.
-
- **Values**: ``0``, ``1``
-
- Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
- assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
- which provides additional assertions about the validity of iterators used by
- the program.
-
- Note that this option has no effect on libc++'s ABI
+ See :ref:`using-debug-mode` for more information.
**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
This macro is used to enable -Wthread-safety annotations on libc++'s
diff --git a/docs/index.rst b/docs/index.rst
index 0cac7fe..c62dfe8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -127,6 +127,7 @@
.. toctree::
:maxdepth: 1
+ DesignDocs/DebugMode
DesignDocs/CapturingConfigInfo
DesignDocs/ABIVersioning
DesignDocs/VisibilityMacros