docs/DesignDocs/DebugMode.rst

   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
  32
  33 **_LIBCPP_DEBUG_USE_EXCEPTIONS**:
  34   When this macro is defined ``_LIBCPP_ASSERT`` failures throw
  35   ``__libcpp_debug_exception`` instead of aborting. Additionally this macro
  36   disables exception specifications on functions containing ``_LIBCPP_ASSERT``
  37   checks. This allows assertion failures to correctly throw through these
  38   functions.
  39
  40 Handling Assertion Failures
  41 ---------------------------
  42
  43 When a debug assertion fails the assertion handler is called via the
  44 ``std::__libcpp_debug_function`` function pointer. It is possible to override
  45 this function pointer using a different handler function. Libc++ provides two
  46 different assertion handlers, the default handler
  47 ``std::__libcpp_abort_debug_handler`` which aborts the program, and
  48 ``std::__libcpp_throw_debug_handler`` which throws an instance of
  49 ``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing
  50 assertion handler as follows:
  51
  52 .. code-block:: cpp
  53
  54   #define _LIBCPP_DEBUG 1
  55   #include <string>
  56   int main() {
  57     std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
  58     try {
  59       std::string::iterator bad_it;
  60       std::string str("hello world");
  61       str.insert(bad_it, '!'); // causes debug assertion
  62     } catch (std::__libcpp_debug_exception const&) {
  63       return EXIT_SUCCESS;
  64     }
  65     return EXIT_FAILURE;
  66   }
  67
  68 Debug Mode Checks
  69 =================
  70
  71 Libc++'s debug mode offers two levels of checking. The first enables various
  72 precondition checks throughout libc++. The second additionally enables
  73 "iterator debugging" which checks the validity of iterators used by the program.
  74
  75 Basic Checks
  76 ============
  77
  78 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
  79
  80 The following checks are enabled by ``_LIBCPP_DEBUG``:
  81
  82   * FIXME: Update this list
  83
  84 Iterator Debugging Checks
  85 =========================
  86
  87 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
  88
  89 The following containers and STL classes support iterator debugging:
  90
  91   * ``std::string``
  92   * ``std::vector<T>`` (``T != bool``)
  93   * ``std::list``
  94   * ``std::unordered_map``
  95   * ``std::unordered_multimap``
  96   * ``std::unordered_set``
  97   * ``std::unordered_multiset``
  98
  99 The remaining containers do not currently support iterator debugging.
 100 Patches welcome.