1 files changed, 91 insertions, 0 deletions
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst b/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst
new file mode 100644
index 00000000000..e4d4e5b2d90
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/DebugMode.rst
@@ -0,0 +1,91 @@
+==========
+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 <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 ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
+
+The following checks are enabled by ``_LIBCPP_DEBUG``:
+
+  * 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>`` (``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.