Home | History | Annotate | Line # | Download | only in DesignDocs 
      1 ==========
      2 Debug Mode
      3 ==========
      4 
      5 .. contents::
      6    :local:
      7 
      8 .. _using-debug-mode:
      9 
     10 Using Debug Mode
     11 ================
     12 
     13 Libc++ provides a debug mode that enables assertions meant to detect incorrect
     14 usage of the standard library. By default these assertions are disabled but
     15 they 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 
     35 Handling Assertion Failures
     36 ---------------------------
     37 
     38 When a debug assertion fails the assertion handler is called via the
     39 ``std::__libcpp_debug_function`` function pointer. It is possible to override
     40 this function pointer using a different handler function. Libc++ provides a
     41 the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
     42 program. The handler may not return. Libc++ can be changed to use a custom
     43 assertion 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 
     59 Debug Mode Checks
     60 =================
     61 
     62 Libc++'s debug mode offers two levels of checking. The first enables various
     63 precondition checks throughout libc++. The second additionally enables
     64 "iterator debugging" which checks the validity of iterators used by the program.
     65 
     66 Basic Checks
     67 ============
     68 
     69 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
     70 
     71 The 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 
     81 Iterator Debugging Checks
     82 =========================
     83 
     84 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
     85 
     86 The 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 
     96 The remaining containers do not currently support iterator debugging.
     97 Patches welcome.
     98