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