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
61Randomizing Unspecified Behavior (``_LIBCPP_DEBUG == 1``)
62---------------------------------------------------------
63This also enables the randomization of unspecified behavior, for
64example, for equal elements in ``std::sort`` or randomizing both parts of
65the partition after ``std::nth_element`` call. This effort helps you to migrate
66to potential future faster versions of these algorithms and deflake your tests
67which depend on such behavior. To fix the seed, use
68``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed`` definition.
69
70Handling Assertion Failures
71===========================
72When a debug assertion fails the assertion handler is called via the
73``std::__libcpp_debug_function`` function pointer. It is possible to override
74this function pointer using a different handler function. Libc++ provides a
75the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
76program. The handler may not return. Libc++ can be changed to use a custom
77assertion handler as follows.
78
79.. code-block:: cpp
80
81  #define _LIBCPP_DEBUG 1
82  #include <string>
83  void my_handler(std::__libcpp_debug_info const&);
84  int main(int, char**) {
85    std::__libcpp_debug_function = &my_handler;
86
87    std::string::iterator bad_it;
88    std::string str("hello world");
89    str.insert(bad_it, '!'); // causes debug assertion
90    // control flow doesn't return
91  }
92