146035553Spatrick========== 246035553SpatrickDebug Mode 346035553Spatrick========== 446035553Spatrick 546035553Spatrick.. contents:: 646035553Spatrick :local: 746035553Spatrick 846035553Spatrick.. _using-debug-mode: 946035553Spatrick 1076d0caaeSpatrickUsing the debug mode 1176d0caaeSpatrick==================== 1246035553Spatrick 1376d0caaeSpatrickLibc++ provides a debug mode that enables special debugging checks meant to detect 1476d0caaeSpatrickincorrect usage of the standard library. These checks are disabled by default, but 15*4bdff4beSrobertthey can be enabled by vendors when building the library by using ``LIBCXX_ENABLE_DEBUG_MODE``. 1646035553Spatrick 17*4bdff4beSrobertSince the debug mode has ABI implications, users should compile their whole program, 18*4bdff4beSrobertincluding any dependent libraries, against a Standard library configured identically 19*4bdff4beSrobertwith respect to the debug mode. In other words, they should not mix code built against 20*4bdff4beSroberta Standard library with the debug mode enabled with code built against a Standard library 21*4bdff4beSrobertwhere the debug mode is disabled. 2246035553Spatrick 23*4bdff4beSrobertFurthermore, users should not rely on a stable ABI being provided when the debug mode is 24*4bdff4beSrobertenabled -- we reserve the right to change the ABI at any time. If you need a stable ABI 25*4bdff4beSrobertand still want some level of hardening, you should look into enabling :ref:`assertions <assertions-mode>` 26*4bdff4beSrobertinstead. 2746035553Spatrick 28*4bdff4beSrobertThe debug mode provides various checks to aid application debugging. 2946035553Spatrick 30*4bdff4beSrobertComparator consistency checks 31*4bdff4beSrobert----------------------------- 32*4bdff4beSrobertLibc++ provides some checks for the consistency of comparators passed to algorithms. Specifically, 33*4bdff4beSrobertmany algorithms such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``, wrap the 34*4bdff4beSrobertuser-provided comparator to assert that `!comp(y, x)` whenever `comp(x, y)`. This can cause the 35*4bdff4beSrobertuser-provided comparator to be evaluated up to twice as many times as it would be without the 36*4bdff4beSrobertdebug mode, and causes the library to violate some of the Standard's complexity clauses. 3746035553Spatrick 38*4bdff4beSrobertIterator bounds checking 39*4bdff4beSrobert------------------------ 40*4bdff4beSrobertThe library provides iterators that ensure they are within the bounds of their container when dereferenced. 41*4bdff4beSrobertArithmetic can be performed on these iterators to create out-of-bounds iterators, but they cannot be dereferenced 42*4bdff4beSrobertwhen out-of-bounds. The following classes currently provide iterators that have bounds checking: 4376d0caaeSpatrick 44*4bdff4beSrobert- ``std::string`` 45*4bdff4beSrobert- ``std::vector<T>`` (``T != bool``) 46*4bdff4beSrobert- ``std::span`` 4776d0caaeSpatrick 48*4bdff4beSrobert.. TODO: Add support for iterator bounds checking in ``std::string_view`` and ``std::array`` 4976d0caaeSpatrick 50*4bdff4beSrobertIterator ownership checking 51*4bdff4beSrobert--------------------------- 52*4bdff4beSrobertThe library provides iterator ownership checking, which allows catching cases where e.g. 53*4bdff4beSrobertan iterator from container ``X`` is used as a position to insert into container ``Y``. 54*4bdff4beSrobertThe following classes support iterator ownership checking: 5576d0caaeSpatrick 5676d0caaeSpatrick- ``std::string`` 5776d0caaeSpatrick- ``std::vector<T>`` (``T != bool``) 5876d0caaeSpatrick- ``std::list`` 5976d0caaeSpatrick- ``std::unordered_map`` 6076d0caaeSpatrick- ``std::unordered_multimap`` 6176d0caaeSpatrick- ``std::unordered_set`` 6276d0caaeSpatrick- ``std::unordered_multiset`` 6376d0caaeSpatrick 64*4bdff4beSrobertRandomizing unspecified behavior 65*4bdff4beSrobert-------------------------------- 66*4bdff4beSrobertThe library supports the randomization of unspecified behavior. For example, randomizing 67*4bdff4beSrobertthe relative order of equal elements in ``std::sort`` or randomizing both parts of the 68*4bdff4beSrobertpartition after calling ``std::nth_element``. This effort helps migrating to potential 69*4bdff4beSrobertfuture faster versions of these algorithms that might not have the exact same behavior. 70*4bdff4beSrobertIn particular, it makes it easier to deflake tests that depend on unspecified behavior. 71*4bdff4beSrobertA seed can be used to make such failures reproducible: use ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed``. 72