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