[libc++] Start classifying debug mode features with more granularity

[ldionne]

Summary

I am starting to granularize debug-mode checks so they can be controlled
more individually. The goal is for vendors to eventually be able to select
which categories of checks they want embedded in their configuration of
the library with more granularity.

Note that this patch is a bit weird on its own because it does not touch
any of the containers that implement iterator bounds checking through the
__dereferenceable check of the legacy debug mode. However, I added TODOs
to string and vector to change that.

[ldionne]

ARM bots are stuck.

libcxx/docs/DesignDocs/DebugMode.rst

 Comparator consistency checks
 -----------------------------
 Libc++ provides some checks for the consistency of comparators passed to algorithms. Specifically,
 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 the
 debug mode, and causes the library to violate some of the Standard's complexity clauses.
 
-Iterator debugging checks
--------------------------
-The library contains various assertions to check the validity of iterators used
-by the program. The following containers and classes support iterator debugging:
+Iterator bounds checking
+------------------------
+The library provides iterators that ensure they are within the bounds of their container when dereferenced.
+Arithmetic can be performed on these iterators to create out-of-bounds iterators, but they cannot be dereferenced
+when out-of-bounds. The following classes currently provide iterators that have bounds checking:
+
+- ``std::string``
+- ``std::vector<T>`` (``T != bool``)
+- ``std::span``
+
+.. TODO: Add support for iterator bounds checking in ``std::string_view`` and ``std::array``
+
+Iterator ownership checking
+---------------------------
+The library provides iterator ownership checking, which allows catching cases where e.g.
+an iterator from container ``X`` is used as a position to insert into container ``Y``.
+The following classes support iterator ownership checking:
 
 - ``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.
-
 Randomizing unspecified behavior
 --------------------------------
 The library supports the randomization of unspecified behavior. For example, randomizing
 the relative order of equal elements in ``std::sort`` or randomizing both parts of the
 partition after calling ``std::nth_element``. This effort helps migrating to potential
 future faster versions of these algorithms that might not have the exact same behavior.
 In particular, it makes it easier to deflake tests that depend on unspecified behavior.
 A seed can be used to make such failures reproducible: use ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed``.

libcxx/include/__debug

 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
 #if defined(_LIBCPP_ENABLE_DEBUG_MODE) && !defined(_LIBCPP_CXX03_LANG) && !defined(_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY)
 # define _LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY
 #endif
 
+#if defined(_LIBCPP_ENABLE_DEBUG_MODE) && !defined(_LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING)
+# define _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
+#endif
+
 #ifdef _LIBCPP_ENABLE_DEBUG_MODE
 #   define _LIBCPP_DEBUG_ASSERT(x, m) _LIBCPP_ASSERT(::std::__libcpp_is_constant_evaluated() || (x), m)
 #else
 #   define _LIBCPP_DEBUG_ASSERT(x, m) ((void)0)
 #endif
 
 #if defined(_LIBCPP_ENABLE_DEBUG_MODE) || defined(_LIBCPP_BUILDING_LIBRARY)
 

libcxx/include/span

//  constants and types
     using element_type           = _Tp;
     using value_type             = remove_cv_t<_Tp>;
     using size_type              = size_t;
     using difference_type        = ptrdiff_t;
     using pointer                = _Tp *;
     using const_pointer          = const _Tp *;
     using reference              = _Tp &;
     using const_reference        = const _Tp &;
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
     using iterator               = __bounded_iter<pointer>;
 #else
     using iterator               = __wrap_iter<pointer>;
 #endif
     using reverse_iterator       = _VSTD::reverse_iterator<iterator>;
 
     static constexpr size_type extent = _Extent;
 
_LIBCPP_INLINE_VISIBILITY constexpr reference back() const noexcept
         _LIBCPP_ASSERT(!empty(), "span<T, N>::back() on empty span");
         return __data_[size()-1];
     }
 
     _LIBCPP_INLINE_VISIBILITY constexpr pointer data()                         const noexcept { return __data_; }
 
 // [span.iter], span iterator support
     _LIBCPP_INLINE_VISIBILITY constexpr iterator begin() const noexcept {
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
         return std::__make_bounded_iter(data(), data(), data() + size());
 #else
         return iterator(this, data());
 #endif
     }
     _LIBCPP_INLINE_VISIBILITY constexpr iterator end() const noexcept {
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
         return std::__make_bounded_iter(data() + size(), data(), data() + size());
 #else
         return iterator(this, data() + size());
 #endif
     }
     _LIBCPP_INLINE_VISIBILITY constexpr reverse_iterator        rbegin() const noexcept { return reverse_iterator(end()); }
     _LIBCPP_INLINE_VISIBILITY constexpr reverse_iterator          rend() const noexcept { return reverse_iterator(begin()); }
 
//  constants and types
     using element_type           = _Tp;
     using value_type             = remove_cv_t<_Tp>;
     using size_type              = size_t;
     using difference_type        = ptrdiff_t;
     using pointer                = _Tp *;
     using const_pointer          = const _Tp *;
     using reference              = _Tp &;
     using const_reference        = const _Tp &;
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
     using iterator               = __bounded_iter<pointer>;
 #else
     using iterator               = __wrap_iter<pointer>;
 #endif
     using reverse_iterator       = _VSTD::reverse_iterator<iterator>;
 
     static constexpr size_type extent = dynamic_extent;
 
_LIBCPP_INLINE_VISIBILITY constexpr reference back() const noexcept
         return __data_[size()-1];
     }
 
 
     _LIBCPP_INLINE_VISIBILITY constexpr pointer data()                         const noexcept { return __data_; }
 
 // [span.iter], span iterator support
     _LIBCPP_INLINE_VISIBILITY constexpr iterator begin() const noexcept {
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
         return std::__make_bounded_iter(data(), data(), data() + size());
 #else
         return iterator(this, data());
 #endif
     }
     _LIBCPP_INLINE_VISIBILITY constexpr iterator end() const noexcept {
-#ifdef _LIBCPP_ENABLE_DEBUG_MODE
+#ifdef _LIBCPP_DEBUG_ITERATOR_BOUNDS_CHECKING
         return std::__make_bounded_iter(data() + size(), data(), data() + size());
 #else
         return iterator(this, data() + size());
 #endif
     }
     _LIBCPP_INLINE_VISIBILITY constexpr reverse_iterator        rbegin() const noexcept { return reverse_iterator(end()); }
     _LIBCPP_INLINE_VISIBILITY constexpr reverse_iterator          rend() const noexcept { return reverse_iterator(begin()); }
 

libcxx/include/string

static_assert(( is_same<_CharT, typename traits_type::char_type>::value),
                   "traits_type::char_type must be the same type as CharT");
     static_assert(( is_same<typename allocator_type::value_type, value_type>::value),
                   "Allocator::value_type must be same type as value_type");
 
     static_assert(is_same<allocator_type, __rebind_alloc<__alloc_traits, value_type> >::value,
                   "[allocator.requirements] states that rebinding an allocator to the same type should result in the "
                   "original allocator");
 
+    // TODO: Implement iterator bounds checking without requiring the global database.
     typedef __wrap_iter<pointer>                         iterator;
     typedef __wrap_iter<const_pointer>                   const_iterator;
     typedef std::reverse_iterator<iterator>              reverse_iterator;
     typedef std::reverse_iterator<const_iterator>        const_reverse_iterator;
 
 private:
     static_assert(CHAR_BIT == 8, "This implementation assumes that one byte contains 8 bits");
 

libcxx/include/vector

public:
     typedef _Allocator                                      allocator_type;
     typedef allocator_traits<allocator_type>                __alloc_traits;
     typedef value_type&                                     reference;
     typedef const value_type&                               const_reference;
     typedef typename __alloc_traits::size_type              size_type;
     typedef typename __alloc_traits::difference_type        difference_type;
     typedef typename __alloc_traits::pointer                pointer;
     typedef typename __alloc_traits::const_pointer          const_pointer;
+    // TODO: Implement iterator bounds checking without requiring the global database.
     typedef __wrap_iter<pointer>                            iterator;
     typedef __wrap_iter<const_pointer>                      const_iterator;
     typedef std::reverse_iterator<iterator>               reverse_iterator;
     typedef std::reverse_iterator<const_iterator>         const_reverse_iterator;
 
     static_assert((is_same<typename allocator_type::value_type, value_type>::value),
                   "Allocator::value_type must be same type as value_type");