head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RELEASE:1.1.1.1 netbsd-11-0-RC7:1.1.1.1 netbsd-11-0-RC6:1.1.1.1 netbsd-11-0-RC5:1.1.1.1 netbsd-11-0-RC4:1.1.1.1 netbsd-11-0-RC3:1.1.1.1 netbsd-11-0-RC2:1.1.1.1 netbsd-11-0-RC1:1.1.1.1 perseant-exfatfs-base-20250801:1.1.1.1 netbsd-11:1.1.1.1.0.10 netbsd-11-base:1.1.1.1 netbsd-10-1-RELEASE:1.1.1.1 perseant-exfatfs-base-20240630:1.1.1.1 perseant-exfatfs:1.1.1.1.0.8 perseant-exfatfs-base:1.1.1.1 netbsd-10-0-RELEASE:1.1.1.1 netbsd-10-0-RC6:1.1.1.1 netbsd-10-0-RC5:1.1.1.1 netbsd-10-0-RC4:1.1.1.1 netbsd-10-0-RC3:1.1.1.1 netbsd-10-0-RC2:1.1.1.1 netbsd-10-0-RC1:1.1.1.1 netbsd-10:1.1.1.1.0.6 netbsd-10-base:1.1.1.1 cjep_sun2x-base1:1.1.1.1 cjep_sun2x:1.1.1.1.0.4 cjep_sun2x-base:1.1.1.1 cjep_staticlib_x:1.1.1.1.0.2 cjep_staticlib_x-base1:1.1.1.1 LLVM-249b40b558955afe5ac2b549edcf2d7f859c8cc9:1.1.1.1 LLVM:1.1.1; locks; strict; comment @# @; 1.1 date 2021.05.30.01.29.20; author joerg; state Exp; branches 1.1.1.1; next ; commitid ELgSWj1pehxUV6VC; 1.1.1.1 date 2021.05.30.01.29.20; author joerg; state Exp; branches 1.1.1.1.2.1; next ; commitid ELgSWj1pehxUV6VC; 1.1.1.1.2.1 date 2021.05.30.01.29.20; author cjep; state dead; branches; next 1.1.1.1.2.2; commitid eWz9SBW0XqKjJlVC; 1.1.1.1.2.2 date 2021.05.31.22.07.31; author cjep; state Exp; branches; next ; commitid eWz9SBW0XqKjJlVC; desc @@ 1.1 log @Initial revision @ text @========== 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 ``_LIBCPP_DEBUG`` macro. **_LIBCPP_DEBUG** Macro ----------------------- **_LIBCPP_DEBUG**: This macro is used to enable assertions and iterator debugging checks within libc++. By default it is undefined. **Values**: ``0``, ``1`` Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging" which provides additional assertions about the validity of iterators used by the program. 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. 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 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 ``_LIBCPP_DEBUG`` is defined to either 0 or 1. The following checks are enabled by ``_LIBCPP_DEBUG``: * 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 ========================= These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. The following containers and STL classes support iterator debugging: * ``std::string`` * ``std::vector`` (``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. @ 1.1.1.1 log @Import libc++ 249b40b558955afe5ac2b549edcf2d7f859c8cc9 @ text @@ 1.1.1.1.2.1 log @file DebugMode.rst was added on branch cjep_staticlib_x on 2021-05-31 22:07:31 +0000 @ text @d1 97 @ 1.1.1.1.2.2 log @sync with head @ text @a0 97 ========== 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 ``_LIBCPP_DEBUG`` macro. **_LIBCPP_DEBUG** Macro ----------------------- **_LIBCPP_DEBUG**: This macro is used to enable assertions and iterator debugging checks within libc++. By default it is undefined. **Values**: ``0``, ``1`` Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging" which provides additional assertions about the validity of iterators used by the program. 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. 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 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 ``_LIBCPP_DEBUG`` is defined to either 0 or 1. The following checks are enabled by ``_LIBCPP_DEBUG``: * 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 ========================= These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. The following containers and STL classes support iterator debugging: * ``std::string`` * ``std::vector`` (``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. @