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
30Comparator consistency checks (``_LIBCPP_DEBUG == 1``)
31------------------------------------------------------
32Libc++ provides some checks for the consistency of comparators passed to algorithms. Specifically,
33many algorithms such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``, wrap the
34user-provided comparator to assert that `!comp(y, x)` whenever `comp(x, y)`. This can cause the
35user-provided comparator to be evaluated up to twice as many times as it would be without the
36debug mode, and causes the library to violate some of the Standard's complexity clauses.
37
38Iterator debugging checks (``_LIBCPP_DEBUG == 1``)
39--------------------------------------------------
40Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging", which provides
41additional assertions about the validity of iterators used by the program.
42
43The following containers and classes support iterator debugging:
44
45- ``std::string``
46- ``std::vector<T>`` (``T != bool``)
47- ``std::list``
48- ``std::unordered_map``
49- ``std::unordered_multimap``
50- ``std::unordered_set``
51- ``std::unordered_multiset``
52
53The remaining containers do not currently support iterator debugging.
54Patches welcome.
55
56Randomizing Unspecified Behavior (``_LIBCPP_DEBUG == 1``)
57---------------------------------------------------------
58This also enables the randomization of unspecified behavior, for
59example, for equal elements in ``std::sort`` or randomizing both parts of
60the partition after ``std::nth_element`` call. This effort helps you to migrate
61to potential future faster versions of these algorithms and deflake your tests
62which depend on such behavior. To fix the seed, use
63``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed`` definition.
64
65Handling Assertion Failures
66===========================
67When a debug assertion fails the assertion handler is called via the
68``std::__libcpp_debug_function`` function pointer. It is possible to override
69this function pointer using a different handler function. Libc++ provides a
70the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
71program. The handler may not return. Libc++ can be changed to use a custom
72assertion handler as follows.
73
74.. code-block:: cpp
75
76  #define _LIBCPP_DEBUG 1
77  #include <string>
78  void my_handler(std::__libcpp_debug_info const&);
79  int main(int, char**) {
80    std::__libcpp_debug_function = &my_handler;
81
82    std::string::iterator bad_it;
83    std::string str("hello world");
84    str.insert(bad_it, '!'); // causes debug assertion
85    // control flow doesn't return
86  }
87