diff options
Diffstat (limited to 'lib/libcxx/docs/DesignDocs/DebugMode.rst')
-rw-r--r-- | lib/libcxx/docs/DesignDocs/DebugMode.rst | 100 |
1 files changed, 0 insertions, 100 deletions
diff --git a/lib/libcxx/docs/DesignDocs/DebugMode.rst b/lib/libcxx/docs/DesignDocs/DebugMode.rst deleted file mode 100644 index 3b997d44607..00000000000 --- a/lib/libcxx/docs/DesignDocs/DebugMode.rst +++ /dev/null @@ -1,100 +0,0 @@ -========== -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. |