1========== 2Debug Mode 3========== 4 5.. contents:: 6 :local: 7 8.. _using-debug-mode: 9 10Using Debug Mode 11================ 12 13Libc++ provides a debug mode that enables assertions meant to detect incorrect 14usage of the standard library. By default these assertions are disabled but 15they can be enabled using the ``_LIBCPP_DEBUG`` macro. 16 17**_LIBCPP_DEBUG** Macro 18----------------------- 19 20**_LIBCPP_DEBUG**: 21 This macro is used to enable assertions and iterator debugging checks within 22 libc++. By default it is undefined. 23 24 **Values**: ``0``, ``1`` 25 26 Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s 27 assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging" 28 which provides additional assertions about the validity of iterators used by 29 the program. 30 31 Note that this option has no effect on libc++'s ABI; but it does have broad 32 ODR implications. Users should compile their whole program at the same 33 debugging level. 34 35Handling Assertion Failures 36--------------------------- 37 38When a debug assertion fails the assertion handler is called via the 39``std::__libcpp_debug_function`` function pointer. It is possible to override 40this function pointer using a different handler function. Libc++ provides a 41the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the 42program. The handler may not return. Libc++ can be changed to use a custom 43assertion handler as follows. 44 45.. code-block:: cpp 46 47 #define _LIBCPP_DEBUG 1 48 #include <string> 49 void my_handler(std::__libcpp_debug_info const&); 50 int main(int, char**) { 51 std::__libcpp_debug_function = &my_handler; 52 53 std::string::iterator bad_it; 54 std::string str("hello world"); 55 str.insert(bad_it, '!'); // causes debug assertion 56 // control flow doesn't return 57 } 58 59Debug Mode Checks 60================= 61 62Libc++'s debug mode offers two levels of checking. The first enables various 63precondition checks throughout libc++. The second additionally enables 64"iterator debugging" which checks the validity of iterators used by the program. 65 66Basic Checks 67============ 68 69These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1. 70 71The following checks are enabled by ``_LIBCPP_DEBUG``: 72 73 * Many algorithms, such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``, 74 wrap the user-provided comparator to assert that `!comp(y, x)` whenever 75 `comp(x, y)`. This can cause the user-provided comparator to be evaluated 76 up to twice as many times as it would be without ``_LIBCPP_DEBUG``, and 77 causes the library to violate some of the Standard's complexity clauses. 78 79 * FIXME: Update this list 80 81Iterator Debugging Checks 82========================= 83 84These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. 85 86The following containers and STL classes support iterator debugging: 87 88 * ``std::string`` 89 * ``std::vector<T>`` (``T != bool``) 90 * ``std::list`` 91 * ``std::unordered_map`` 92 * ``std::unordered_multimap`` 93 * ``std::unordered_set`` 94 * ``std::unordered_multiset`` 95 96The remaining containers do not currently support iterator debugging. 97Patches welcome. 98