dependencies/libcudacxx/libcxx/docs/DesignDocs/DebugMode_BACKUP_23341.rst

==========
Debug Mode
==========

.. contents::
   :local:

.. _using-debug-mode:

Using Debug Mode
================

Libc++ provides a debug mode that enables assertions meant to detect incorrect
usage of the standard library. By default these assertions are disabled but
they can be enabled using the ``_LIBCUDACXX_DEBUG`` macro.

**_LIBCUDACXX_DEBUG** Macro
-----------------------

**_LIBCUDACXX_DEBUG**:
  This macro is used to enable assertions and iterator debugging checks within
  libc++. By default it is undefined.

  **Values**: ``0``, ``1``

  Defining ``_LIBCUDACXX_DEBUG`` to ``0`` or greater enables most of libc++'s
  assertions. Defining ``_LIBCUDACXX_DEBUG`` to ``1`` enables "iterator debugging"
  which provides additional assertions about the validity of iterators used by
  the program.

<<<<<<< HEAD
  Note that this option has no effect on libc++'s ABI

**_LIBCUDACXX_DEBUG_USE_EXCEPTIONS**:
  When this macro is defined ``_LIBCUDACXX_ASSERT`` failures throw
  ``__libcpp_debug_exception`` instead of aborting. Additionally this macro
  disables exception specifications on functions containing ``_LIBCUDACXX_ASSERT``
  checks. This allows assertion failures to correctly throw through these
  functions.
=======
  Note that this option has no effect on libc++'s ABI; but it does have broad
  ODR implications. Users should compile their whole program at the same
  debugging level.
>>>>>>> 48a15a7b3a9f02fd60fceb28adcdf7aea7a1b1da

Handling Assertion Failures
---------------------------

When a debug assertion fails the assertion handler is called via the
``std::__libcpp_debug_function`` function pointer. It is possible to override
this function pointer using a different handler function. Libc++ provides a
the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
program. The handler may not return. Libc++ can be changed to use a custom
assertion handler as follows.

.. code-block:: cpp

  #define _LIBCUDACXX_DEBUG 1
  #include <string>
  void my_handler(std::__libcpp_debug_info const&);
  int main(int, char**) {
    std::__libcpp_debug_function = &my_handler;

    std::string::iterator bad_it;
    std::string str("hello world");
    str.insert(bad_it, '!'); // causes debug assertion
    // control flow doesn't return
  }

Debug Mode Checks
=================

Libc++'s debug mode offers two levels of checking. The first enables various
precondition checks throughout libc++. The second additionally enables
"iterator debugging" which checks the validity of iterators used by the program.

Basic Checks
============

These checks are enabled when ``_LIBCUDACXX_DEBUG`` is defined to either 0 or 1.

The following checks are enabled by ``_LIBCUDACXX_DEBUG``:

  * FIXME: Update this list

Iterator Debugging Checks
=========================

These checks are enabled when ``_LIBCUDACXX_DEBUG`` is defined to 1.

The following containers and STL classes support iterator debugging:

  * ``std::string``
  * ``std::vector<T>`` (``T != bool``)
  * ``std::list``
  * ``std::unordered_map``
  * ``std::unordered_multimap``
  * ``std::unordered_set``
  * ``std::unordered_multiset``

The remaining containers do not currently support iterator debugging.
Patches welcome.