83 lines
3.0 KiB
ReStructuredText
83 lines
3.0 KiB
ReStructuredText
==========
|
|
Debug Mode
|
|
==========
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _using-debug-mode:
|
|
|
|
Using the debug mode
|
|
====================
|
|
|
|
Libc++ provides a debug mode that enables special debugging checks meant to detect
|
|
incorrect usage of the standard library. These checks are disabled by default, but
|
|
they can be enabled using the ``_LIBCPP_DEBUG`` macro.
|
|
|
|
Note that using the debug mode discussed in this document requires that the library
|
|
has been compiled with support for the debug mode (see ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT``).
|
|
|
|
Also note that while the debug mode has no effect on libc++'s ABI, it does have broad ODR
|
|
implications. Users should compile their whole program at the same debugging level.
|
|
|
|
The various levels of checking provided by the debug mode follow.
|
|
|
|
No debugging checks (``_LIBCPP_DEBUG`` not defined)
|
|
---------------------------------------------------
|
|
When ``_LIBCPP_DEBUG`` is not defined, there are no debugging checks performed by
|
|
the library. This is the default.
|
|
|
|
Basic checks (``_LIBCPP_DEBUG == 0``)
|
|
-------------------------------------
|
|
When ``_LIBCPP_DEBUG`` is defined to ``0`` (to be understood as level ``0``), some
|
|
debugging checks are enabled. The non-exhaustive list of things is:
|
|
|
|
- Many algorithms, such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``,
|
|
wrap the user-provided comparator to assert that `!comp(y, x)` whenever
|
|
`comp(x, y)`. This can cause the user-provided comparator to be evaluated
|
|
up to twice as many times as it would be without ``_LIBCPP_DEBUG``, and
|
|
causes the library to violate some of the Standard's complexity clauses.
|
|
|
|
- FIXME: Update this list
|
|
|
|
Iterator debugging checks (``_LIBCPP_DEBUG == 1``)
|
|
--------------------------------------------------
|
|
Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging", which provides
|
|
additional assertions about the validity of iterators used by the program.
|
|
|
|
The following containers and 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.
|
|
|
|
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 _LIBCPP_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
|
|
}
|