Import libc++ 10.0.1 release.

10 files changed, 1461 insertions, 0 deletions

diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst b/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst
new file mode 100644
index 00000000000..5960dd18610
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/ABIVersioning.rst
@@ -0,0 +1,17 @@
+
+====================
+Libc++ ABI stability
+====================
+
+Libc++ aims to preserve stable ABI to avoid subtle bugs when code built to the old ABI
+is linked with the code build to the new ABI. At the same time, libc++ allows ABI-breaking
+improvements and bugfixes for the scenarios when ABI change is not a issue.
+
+To support both cases, libc++ allows specifying the ABI version at the
+build time.  The version is defined with a cmake option
+LIBCXX_ABI_VERSION. Another option LIBCXX_ABI_UNSTABLE can be used to
+include all present ABI breaking features. These options translate
+into C++ macro definitions _LIBCPP_ABI_VERSION, _LIBCPP_ABI_UNSTABLE.
+
+Any ABI-changing feature is placed under it's own macro, _LIBCPP_ABI_XXX, which is enabled
+based on the value of _LIBCPP_ABI_VERSION. _LIBCPP_ABI_UNSTABLE, if set, enables all features at once.
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst b/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst
new file mode 100644
index 00000000000..f076dfecdaa
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/AvailabilityMarkup.rst
@@ -0,0 +1,105 @@
+===================
+Availability Markup
+===================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ is used as a system library on macOS and iOS (amongst others). In order
+for users to be able to compile a binary that is intended to be deployed to an
+older version of the platform, clang provides the
+`availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_
+that can be placed on declarations to describe the lifecycle of a symbol in the
+library.
+
+Design
+======
+
+When a new feature is introduced that requires dylib support, a macro should be
+created in include/__config to mark this feature as unavailable for all the
+systems. For example::
+
+    // Define availability macros.
+    #if defined(_LIBCPP_USE_AVAILABILITY_APPLE)
+    # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
+    #else  if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR)
+    # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
+    #else
+    # define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
+    #endif
+
+When the library is updated by the platform vendor, the markup can be updated.
+For example::
+
+    #define _LIBCPP_AVAILABILITY_SHARED_MUTEX                                  \
+      __attribute__((availability(macosx,strict,introduced=10.12)))            \
+      __attribute__((availability(ios,strict,introduced=10.0)))                \
+      __attribute__((availability(tvos,strict,introduced=10.0)))               \
+      __attribute__((availability(watchos,strict,introduced=3.0)))
+
+In the source code, the macro can be added on a class if the full class requires
+type info from the library for example::
+
+    _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL
+    class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access
+      : public std::logic_error {
+
+or on a particular symbol:
+
+    _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void  operator delete(void* __p, std::size_t __sz) _NOEXCEPT;
+
+Furthermore, a lit feature should be added to match that availability macro,
+so that tests depending on that feature can be marked to XFAIL if the feature
+is not supported. This way, the test suite will work on platforms that have
+not shipped the feature yet. This can be done by adding the appropriate lit
+feature in test/config.py.
+
+
+Testing
+=======
+
+Some parameters can be passed to lit to run the test-suite and exercise the
+availability.
+
+* The `platform` parameter controls the deployment target. For example lit can
+  be invoked with `--param=platform=macosx10.8`. Default is the current host.
+* The `use_system_cxx_lib` parameter indicates to use another library than the
+  just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run
+  the test-suite against the host system library. Alternatively a path to the
+  directory containing a specific prebuilt libc++ can be used, for example:
+  `--param=use_system_cxx_lib=/path/to/macOS/10.8/`.
+
+Tests can be marked as XFAIL based on multiple features made available by lit:
+
+
+* if `--param=platform=macosx10.8` is passed, the following features will be available:
+
+  - availability
+  - availability=x86_64
+  - availability=macosx
+  - availability=x86_64-macosx
+  - availability=x86_64-apple-macosx10.8
+  - availability=macosx10.8
+
+  This feature is used to XFAIL a test that *is* using a class or a method marked
+  as unavailable *and* that is expected to *fail* if deployed on an older system.
+
+* if `use_system_cxx_lib` and `--param=platform=macosx10.8` are passed to lit,
+  the following features will also be available:
+
+  - with_system_cxx_lib
+  - with_system_cxx_lib=x86_64
+  - with_system_cxx_lib=macosx
+  - with_system_cxx_lib=x86_64-macosx
+  - with_system_cxx_lib=x86_64-apple-macosx10.8
+  - with_system_cxx_lib=macosx10.8
+
+  This feature is used to XFAIL a test that is *not* using a class or a method
+  marked as unavailable *but* that is expected to fail if deployed on an older
+  system. For example, if the test exhibits a bug in the libc on a particular
+  system version, or if the test uses a symbol that is not available on an
+  older version of the dylib (but for which there is no availability markup,
+  otherwise the XFAIL should use `availability` above).
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst b/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst
new file mode 100644
index 00000000000..8f2d0cd2dd6
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/CapturingConfigInfo.rst
@@ -0,0 +1,86 @@
+=======================================================
+Capturing configuration information during installation
+=======================================================
+
+.. contents::
+   :local:
+
+The Problem
+===========
+
+Currently the libc++ supports building the library with a number of different
+configuration options.  Unfortunately all of that configuration information is
+lost when libc++ is installed. In order to support "persistent"
+configurations libc++ needs a mechanism to capture the configuration options
+in the INSTALLED headers.
+
+
+Design Goals
+============
+
+* The solution should not INSTALL any additional headers. We don't want an extra
+  #include slowing everybody down.
+
+* The solution should not unduly affect libc++ developers. The problem is limited
+  to installed versions of libc++ and the solution should be as well.
+
+* The solution should not modify any existing headers EXCEPT during installation.
+  It makes developers lives harder if they have to regenerate the libc++ headers
+  every time they are modified.
+
+* The solution should not make any of the libc++ headers dependent on
+  files generated by the build system. The headers should be able to compile
+  out of the box without any modification.
+
+* The solution should not have ANY effect on users who don't need special
+  configuration options. The vast majority of users will never need this so it
+  shouldn't cost them.
+
+
+The Solution
+============
+
+When you first configure libc++ using CMake we check to see if we need to
+capture any options. If we haven't been given any "persistent" options then
+we do NOTHING.
+
+Otherwise we create a custom installation rule that modifies the installed __config
+header. The rule first generates a dummy "__config_site" header containing the required
+#defines. The contents of the dummy header are then prepended to the installed
+__config header. By manually prepending the files we avoid the cost of an
+extra #include and we allow the __config header to be ignorant of the extra
+configuration all together. An example "__config" header generated when
+-DLIBCXX_ENABLE_THREADS=OFF is given to CMake would look something like:
+
+.. code-block:: cpp
+
+  //===----------------------------------------------------------------------===//
+  //
+  // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+  // See https://llvm.org/LICENSE.txt for license information.
+  // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+  //
+  //===----------------------------------------------------------------------===//
+
+  #ifndef _LIBCPP_CONFIG_SITE
+  #define _LIBCPP_CONFIG_SITE
+
+  /* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */
+  /* #undef _LIBCPP_HAS_NO_STDIN */
+  /* #undef _LIBCPP_HAS_NO_STDOUT */
+  #define _LIBCPP_HAS_NO_THREADS
+  /* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */
+  /* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */
+
+  #endif
+  // -*- C++ -*-
+  //===--------------------------- __config ---------------------------------===//
+  //
+  // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+  // See https://llvm.org/LICENSE.txt for license information.
+  // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+  //
+  //===----------------------------------------------------------------------===//
+
+  #ifndef _LIBCPP_CONFIG
+  #define _LIBCPP_CONFIG
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.
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst b/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst
new file mode 100644
index 00000000000..2241496d594
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/ExperimentalFeatures.rst
@@ -0,0 +1,203 @@
+=====================
+Experimental Features
+=====================
+
+.. contents::
+   :local:
+
+.. _experimental features:
+
+Overview
+========
+
+Libc++ implements technical specifications (TSes) and ships them as experimental
+features that users are free to try out. The goal is to allow getting feedback
+on those experimental features.
+
+However, libc++ does not provide the same guarantees about those features as
+it does for the rest of the library. In particular, no ABI or API stability
+is guaranteed, and experimental features are deprecated once the non-experimental
+equivalent has shipped in the library. This document outlines the details of
+that process.
+
+Background
+==========
+
+The "end game" of a Technical Specification (TS) is to have the features in
+there added to a future version of the C++ Standard. When this happens, the TS
+can be retired. Sometimes, only part of at TS is added to the standard, and
+the rest of the features may be incorporated into the next version of the TS.
+
+Adoption leaves library implementors with two implementations of a feature,
+one in namespace ``std``, and the other in namespace ``std::experimental``.
+The first one will continue to evolve (via issues and papers), while the other
+will not. Gradually they will diverge. It's not good for users to have two
+(subtly) different implementations of the same functionality in the same library.
+
+Design
+======
+
+When a feature is adopted into the main standard, we implement it in namespace
+``std``. Once that implementation is complete, we then create a deprecation
+warning for the corresponding experimental feature warning users to move off
+of it and to the now-standardized feature.
+
+These deprecation warnings are guarded by a macro of the form
+``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which
+can be defined by users to disable the deprecation warning. Whenever
+possible, deprecation warnings are put on a per-declaration basis
+using the ``[[deprecated]]`` attribute, which also allows disabling
+the warnings using ``-Wno-deprecated-declarations``.
+
+After **2 releases** of LLVM, the experimental feature is removed completely
+(and the deprecation notice too). Using the experimental feature simply becomes
+an error. Furthermore, when an experimental header becomes empty due to the
+removal of the corresponding experimental feature, the header is removed.
+Keeping the header around creates incorrect assumptions from users and breaks
+``__has_include``.
+
+
+Status of TSes
+==============
+
+Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__
+---------------------------------------------------------------------------------------------
+
+Most (but not all) of the features of the LFTS were accepted into C++17.
+
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| Section | Feature                                               | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes                   |
++=========+=======================================================+====================+==========================================+=========================+
+| 2.1     | ``uses_allocator construction``                       | 5.0                | 7.0                                      |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.1.2   | ``erased_type``                                       |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.2.1   | ``tuple_size_v``                                      | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.2.2   | ``apply``                                             | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.3.1   | All of the ``_v`` traits in ``<type_traits>``         | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.3.2   | ``invocation_type`` and ``raw_invocation_type``       |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.3.3   | Logical operator traits                               | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.3.3   | Detection Idiom                                       | 5.0                |                                          | Only partially in C++17 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.4.1   | All of the ``_v`` traits in ``<ratio>``               | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.5.1   | All of the ``_v`` traits in ``<chrono>``              | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.6.1   | All of the ``_v`` traits in ``<system_error>``        | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 3.7     | ``propagate_const``                                   |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 4.2     | Enhancements to ``function``                          | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 4.3     | searchers                                             | 7.0                | 9.0                                      |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 5       | optional                                              | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 6       | ``any``                                               | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 7       | ``string_view``                                       | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.2.1   | ``shared_ptr`` enhancements                           | Not yet            | Never added                              |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.2.2   | ``weak_ptr`` enhancements                             | Not yet            | Never added                              |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.5     | ``memory_resource``                                   | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.6     | ``polymorphic_allocator``                             | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.7     | ``resource_adaptor``                                  |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.8     | Access to program-wide ``memory_resource`` objects    | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.9     | Pool resource classes                                 | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.10    | ``monotonic_buffer_resource``                         | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.11    | Alias templates using polymorphic memory resources    | Not yet            |                                          |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 8.12    | Non-owning pointers                                   |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 11.2    | ``promise``                                           |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 11.3    | ``packaged_task``                                     |                    | n/a                                      | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 12.2    | ``search``                                            | 7.0                | 9.0                                      |                         |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 12.3    | ``sample``                                            | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 12.4    | ``shuffle``                                           |                    |                                          | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 13.1    | ``gcd`` and ``lcm``                                   | 5.0                | 7.0                                      | Removed                 |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 13.2    | Random number generation                              |                    |                                          | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+| 14      | Reflection Library                                    |                    |                                          | Not part of C++17       |
++---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+
+
+`FileSystem TS <https://wg21.link/N4100>`__
+-------------------------------------------
+The FileSystem TS was accepted (in totality) for C++17.
+The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and will be removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).
+
+Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__
+------------------------------------------------------------------------------------
+Some (most) of the Parallelism TS was accepted for C++17.
+We have not yet shipped an implementation of the Parallelism TS.
+
+`Coroutines TS <https://wg21.link/N4680>`__
+-------------------------------------------
+The Coroutines TS is not yet part of a shipping standard.
+We are shipping (as of v5.0) an implementation of the Coroutines TS in namespace ``std::experimental``.
+
+`Networking TS <https://wg21.link/N4656>`__
+-------------------------------------------
+The Networking TS is not yet part of a shipping standard.
+We have not yet shipped an implementation of the Networking TS.
+
+`Ranges TS <https://wg21.link/N4685>`__
+---------------------------------------
+The Ranges TS is not yet part of a shipping standard.
+We have not yet shipped an implementation of the Ranges TS.
+
+`Concepts TS <https://wg21.link/N4641>`__
+-----------------------------------------
+The Concepts TS is not yet part of a shipping standard, but it has been adopted into the C++20 working draft.
+We have not yet shipped an implementation of the Concepts TS.
+
+`Concurrency TS <https://wg21.link/P0159>`__
+--------------------------------------------
+The Concurrency TS was adopted in Kona (2015).
+None of the Concurrency TS was accepted for C++17.
+We have not yet shipped an implementation of the Concurrency TS.
+
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | Section | Feature                                               | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes                   |
+.. +=========+=======================================================+====================+==========================================+=========================+
+.. | 2.3     | class template ``future``                             |                    |                                          |                         |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.4     | class template ``shared_future``                      |                    |                                          |                         |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.5     | class template ``promise``                            |                    |                                          | Only using ``future``   |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.6     | class template ``packaged_task``                      |                    |                                          | Only using ``future``   |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.7     | function template ``when_all``                        |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.8     | class template ``when_any_result``                    |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.9     | function template ``when_any``                        |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.10    | function template ``make_ready_future``               |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 2.11    | function template ``make_exeptional_future``          |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 3       | ``latches`` and ``barriers``                          |                    |                                          | Not part of C++17       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
+.. | 4       | Atomic Smart Pointers                                 |                    |                                          | Adopted for C++20       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst b/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst
new file mode 100644
index 00000000000..e9e3fc4d230
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/ExtendedCXX03Support.rst
@@ -0,0 +1,118 @@
+=======================
+Extended C++03 Support
+=======================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+libc++ is an implementation of the C++ standard library targeting C++11 or later.
+
+In C++03, the library implements the C++11 standard using C++11 language extensions provided
+by Clang.
+
+This document tracks the C++11 extensions libc++ requires, the C++11 extensions it provides,
+and how to write minimal C++11 inside libc++.
+
+Required C++11 Compiler Extensions
+==================================
+
+Clang provides a large subset of C++11 in C++03 as an extension. The features
+libc++ expects Clang  to provide are:
+
+* Variadic templates.
+* RValue references and perfect forwarding.
+* Alias templates
+* defaulted and deleted Functions.
+* reference qualified Functions
+
+There are also features that Clang *does not* provide as an extension in C++03
+mode. These include:
+
+* ``constexpr`` and ``noexcept``
+* ``auto``
+*  Trailing return types.
+* ``>>`` without a space.
+
+
+Provided C++11 Library Extensions
+=================================
+
+.. warning::
+  The C++11 extensions libc++ provides in C++03 are currently undergoing change. Existing extensions
+  may be removed in the future. New users are strongly discouraged depending on these extension
+  in new code.
+
+  This section will be updated once the libc++ developer community has further discussed the
+  future of C++03 with libc++.
+
+
+Using Minimal C++11 in libc++
+=============================
+
+This section is for developers submitting patches to libc++. It describes idioms that should be
+used in libc++ code, even in C++03, and the reasons behind them.
+
+
+Use Alias Templates over Class Templates
+----------------------------------------
+
+Alias templates should be used instead of class templates in metaprogramming. Unlike class templates,
+Alias templates do not produce a new instantiation every time they are used. This significantly
+decreases the amount of memory used by the compiler.
+
+For example, libc++ should not use ``add_const`` internally. Instead it should use an alias template
+like
+
+.. code-block:: cpp
+
+  template <class _Tp>
+  using _AddConst = const _Tp;
+
+Use Default Template Parameters for SFINAE
+------------------------------------------
+
+There are three places in a function declaration that SFINAE may occur: In the template parameter list,
+in the function parameter list, and in the return type. For example:
+
+.. code-block:: cpp
+
+  template <class _Tp, class _ = enable_if_t</*...*/ >
+  void foo(_Tp); // #1
+
+  template <class _Tp>
+  void bar(_Tp, enable_if_t</*...*/>* = nullptr); // # 2
+
+  template <class _Tp>
+  enable_if_t</*...*/> baz(_Tp); // # 3
+
+Using default template parameters for SFINAE (#1) should always be prefered.
+
+Option #2 has two problems. First, users can observe and accidentally pass values to the SFINAE
+function argument. Second, the default arguement creates a live variable, which causes debug
+information to be emitted containing the text of the SFINAE.
+
+Option #3 can also cause more debug information to be emitted than is needed, because the function
+return type will appear in the debug information.
+
+Use ``unique_ptr`` when allocating memory
+------------------------------------------
+
+The standard library often needs to allocate memory and then construct a user type in it.
+If the users constructor throws, the library needs to deallocate that memory. The idiomatic way to
+achieve this is with ``unique_ptr``.
+
+``__builtin_new_allocator`` is an example of this idiom. Example usage would look like:
+
+.. code-block:: cpp
+
+  template <class T>
+  T* __create() {
+    using _UniquePtr = unique_ptr<void*, __default_new_allocator::__default_new_deleter>;
+    _UniquePtr __p = __default_new_allocator::__allocate_bytes(sizeof(T), alignof(T));
+    T* __res = ::new(__p.get()) T();
+    (void)__p.release();
+    return __res;
+  }
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst b/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst
new file mode 100644
index 00000000000..2fbba6547bb
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/FeatureTestMacros.rst
@@ -0,0 +1,45 @@
+===================
+Feature Test Macros
+===================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ implements the C++ feature test macros as specified in the C++2a standard,
+and before that in non-normative guiding documents
+(`See cppreference <https://en.cppreference.com/w/User:D41D8CD98F/feature_testing_macros>`_)
+
+
+Design
+======
+
+Feature test macros are tricky to track, implement, test, and document correctly.
+They must be available from a list of headers, they may have different values in
+different dialects, and they may or may not be implemented by libc++. In order to
+track all of these conditions correctly and easily, we want a Single Source of
+Truth (SSoT) that defines each feature test macro, its values, the headers it
+lives in, and whether or not is is implemented by libc++. From this SSoA we
+have enough information to automatically generate the `<version>` header,
+the tests, and the documentation.
+
+Therefore we maintain a SSoA in `libcxx/utils/generate_feature_test_macro_components.py`
+which doubles as a script to generate the following components:
+
+* The `<version>` header.
+* The version tests under `support.limits.general`.
+* Documentation of libc++'s implementation of each macro.
+
+Usage
+=====
+
+The `generate_feature_test_macro_components.py` script is used to track and
+update feature test macros in libc++.
+
+Whenever a feature test macro is added or changed, the table should be updated
+and the script should be re-ran. The script will clobber the existing test files
+and the documentation and it will generate a new `<version>` header as a
+temporary file. The generated `<version>` header should be merged with the
+existing one.
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst b/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst
new file mode 100644
index 00000000000..f1e9edd8735
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/FileTimeType.rst
@@ -0,0 +1,495 @@
+==============
+File Time Type
+==============
+
+.. contents::
+   :local:
+
+.. _file-time-type-motivation:
+
+Motivation
+==========
+
+The filesystem library provides interfaces for getting and setting the last
+write time of a file or directory. The interfaces use the ``file_time_type``
+type, which is a specialization of ``chrono::time_point`` for the
+"filesystem clock". According to [fs.filesystem.syn]
+
+  trivial-clock is an implementation-defined type that satisfies the
+  Cpp17TrivialClock requirements ([time.clock.req]) and that is capable of
+  representing and measuring file time values. Implementations should ensure
+  that the resolution and range of file_­time_­type reflect the operating
+  system dependent resolution and range of file time values.
+
+
+On POSIX systems, file times are represented using the ``timespec`` struct,
+which is defined as follows:
+
+.. code-block:: cpp
+
+  struct timespec {
+    time_t tv_sec;
+    long   tv_nsec;
+  };
+
+To represent the range and resolution of ``timespec``, we need to (A) have
+nanosecond resolution, and (B) use more than 64 bits (assuming a 64 bit ``time_t``).
+
+As the standard requires us to use the ``chrono`` interface, we have to define
+our own filesystem clock which specifies the period and representation of
+the time points and duration it provides. It will look like this:
+
+.. code-block:: cpp
+
+  struct _FilesystemClock {
+    using period = nano;
+    using rep = TBD; // What is this?
+
+    using duration = chrono::duration<rep, period>;
+    using time_point = chrono::time_point<_FilesystemClock>;
+
+    // ... //
+  };
+
+  using file_time_type = _FilesystemClock::time_point;
+
+
+To get nanosecond resolution, we simply define ``period`` to be ``std::nano``.
+But what type can we use as the arithmetic representation that is capable
+of representing the range of the ``timespec`` struct?
+
+Problems To Consider
+====================
+
+Before considering solutions, let's consider the problems they should solve,
+and how important solving those problems are:
+
+
+Having a Smaller Range than ``timespec``
+----------------------------------------
+
+One solution to the range problem is to simply reduce the resolution of
+``file_time_type`` to be less than that of nanoseconds. This is what libc++'s
+initial implementation of ``file_time_type`` did; it's also what
+``std::system_clock`` does. As a result, it can represent time points about
+292 thousand years on either side of the epoch, as opposed to only 292 years
+at nanosecond resolution.
+
+``timespec`` can represent time points +/- 292 billion years from the epoch
+(just in case you needed a time point 200 billion years before the big bang,
+and with nanosecond resolution).
+
+To get the same range, we would need to drop our resolution to that of seconds
+to come close to having the same range.
+
+This begs the question, is the range problem "really a problem"? Sane usages
+of file time stamps shouldn't exceed +/- 300 years, so should we care to support it?
+
+I believe the answer is yes. We're not designing the filesystem time API, we're
+providing glorified C++ wrappers for it. If the underlying API supports
+a value, then we should too. Our wrappers should not place artificial restrictions
+on users that are not present in the underlying filesystem.
+
+Having a smaller range that the underlying filesystem forces the
+implementation to report ``value_too_large`` errors when it encounters a time
+point that it can't represent. This can cause the call to ``last_write_time``
+to throw in cases where the user was confident the call should succeed. (See below)
+
+
+.. code-block:: cpp
+
+  #include <filesystem>
+  using namespace std::filesystem;
+
+  // Set the times using the system interface.
+  void set_file_times(const char* path, struct timespec ts) {
+    timespec both_times[2];
+    both_times[0] = ts;
+    both_times[1] = ts;
+    int result = ::utimensat(AT_FDCWD, path, both_times, 0);
+    assert(result != -1);
+  }
+
+  // Called elsewhere to set the file time to something insane, and way
+  // out of the 300 year range we might expect.
+  void some_bad_persons_code() {
+    struct timespec new_times;
+    new_times.tv_sec = numeric_limits<time_t>::max();
+    new_times.tv_nsec = 0;
+    set_file_times("/tmp/foo", new_times); // OK, supported by most FSes
+  }
+
+  int main(int, char**) {
+    path p = "/tmp/foo";
+    file_status st = status(p);
+    if (!exists(st) || !is_regular_file(st))
+      return 1;
+    if ((st.permissions() & perms::others_read) == perms::none)
+      return 1;
+    // It seems reasonable to assume this call should succeed.
+    file_time_type tp = last_write_time(p); // BAD! Throws value_too_large.
+    return 0;
+  }
+
+
+Having a Smaller Resolution than ``timespec``
+---------------------------------------------
+
+As mentioned in the previous section, one way to solve the range problem
+is by reducing the resolution. But matching the range of ``timespec`` using a
+64 bit representation requires limiting the resolution to seconds.
+
+So we might ask: Do users "need" nanosecond precision? Is seconds not good enough?
+I limit my consideration of the point to this: Why was it not good enough for
+the underlying system interfaces? If it wasn't good enough for them, then it
+isn't good enough for us. Our job is to match the filesystems range and
+representation, not design it.
+
+
+Having a Larger Range than ``timespec``
+----------------------------------------
+
+We should also consider the opposite problem of having a ``file_time_type``
+that is able to represent a larger range than ``timespec``. At least in
+this case ``last_write_time`` can be used to get and set all possible values
+supported by the underlying filesystem; meaning ``last_write_time(p)`` will
+never throw a overflow error when retrieving a value.
+
+However, this introduces a new problem, where users are allowed to attempt to
+create a time point beyond what the filesystem can represent. Two particular
+values which cause this are ``file_time_type::min()`` and
+``file_time_type::max()``. As a result, the following code would throw:
+
+.. code-block:: cpp
+
+  void test() {
+    last_write_time("/tmp/foo", file_time_type::max()); // Throws
+    last_write_time("/tmp/foo", file_time_type::min()); // Throws.
+  }
+
+Apart from cases explicitly using ``min`` and ``max``, I don't see users taking
+a valid time point, adding a couple hundred billions of years in error,
+and then trying to update a file's write time to that value very often.
+
+Compared to having a smaller range, this problem seems preferable. At least
+now we can represent any time point the filesystem can, so users won't be forced
+to revert back to system interfaces to avoid limitations in the C++ STL.
+
+I posit that we should only consider this concern *after* we have something
+with at least the same range and resolution of the underlying filesystem. The
+latter two problems are much more important to solve.
+
+Potential Solutions And Their Complications
+===========================================
+
+Source Code Portability Across Implementations
+-----------------------------------------------
+
+As we've discussed, ``file_time_type`` needs a representation that uses more
+than 64 bits. The possible solutions include using ``__int128_t``, emulating a
+128 bit integer using a class, or potentially defining a ``timespec`` like
+arithmetic type. All three will allow us to, at minimum, match the range
+and resolution, and the last one might even allow us to match them exactly.
+
+But when considering these potential solutions we need to consider more than
+just the values they can represent. We need to consider the effects they will
+have on users and their code. For example, each of them breaks the following
+code in some way:
+
+.. code-block:: cpp
+
+  // Bug caused by an unexpected 'rep' type returned by count.
+  void print_time(path p) {
+    // __int128_t doesn't have streaming operators, and neither would our
+    // custom arithmetic types.
+    cout << last_write_time(p).time_since_epoch().count() << endl;
+  }
+
+  // Overflow during creation bug.
+  file_time_type timespec_to_file_time_type(struct timespec ts) {
+    // woops! chrono::seconds and chrono::nanoseconds use a 64 bit representation
+    // this may overflow before it's converted to a file_time_type.
+    auto dur = seconds(ts.tv_sec) + nanoseconds(ts.tv_nsec);
+    return file_time_type(dur);
+  }
+
+  file_time_type correct_timespec_to_file_time_type(struct timespec ts) {
+    // This is the correct version of the above example, where we
+    // avoid using the chrono typedefs as they're not sufficient.
+    // Can we expect users to avoid this bug?
+    using fs_seconds = chrono::duration<file_time_type::rep>;
+    using fs_nanoseconds = chrono::duration<file_time_type::rep, nano>;
+    auto dur = fs_seconds(ts.tv_sec) + fs_nanoseconds(tv.tv_nsec);
+    return file_time_type(dur);
+  }
+
+  // Implicit truncation during conversion bug.
+  intmax_t get_time_in_seconds(path p) {
+    using fs_seconds = duration<file_time_type::rep, ratio<1, 1> >;
+    auto tp = last_write_time(p);
+
+    // This works with truncation for __int128_t, but what does it do for
+    // our custom arithmetic types.
+    return duration_cast<fs_seconds>().count();
+  }
+
+
+Each of the above examples would require a user to adjust their filesystem code
+to the particular eccentricities of the representation, hopefully only in such
+a way that the code is still portable across implementations.
+
+At least some of the above issues are unavoidable, no matter what
+representation we choose. But some representations may be quirkier than others,
+and, as I'll argue later, using an actual arithmetic type (``__int128_t``)
+provides the least aberrant behavior.
+
+
+Chrono and ``timespec`` Emulation.
+----------------------------------
+
+One of the options we've considered is using something akin to ``timespec``
+to represent the ``file_time_type``. It only seems natural seeing as that's
+what the underlying system uses, and because it might allow us to match
+the range and resolution exactly. But would it work with chrono? And could
+it still act at all like a ``timespec`` struct?
+
+For ease of consideration, let's consider what the implementation might
+look like.
+
+.. code-block:: cpp
+
+  struct fs_timespec_rep {
+    fs_timespec_rep(long long v)
+      : tv_sec(v / nano::den), tv_nsec(v % nano::den)
+    { }
+  private:
+    time_t tv_sec;
+    long tv_nsec;
+  };
+  bool operator==(fs_timespec_rep, fs_timespec_rep);
+  fs_int128_rep operator+(fs_timespec_rep, fs_timespec_rep);
+  // ... arithmetic operators ... //
+
+The first thing to notice is that we can't construct ``fs_timespec_rep`` like
+a ``timespec`` by passing ``{secs, nsecs}``. Instead we're limited to
+constructing it from a single 64 bit integer.
+
+We also can't allow the user to inspect the ``tv_sec`` or ``tv_nsec`` values
+directly. A ``chrono::duration`` represents its value as a tick period and a
+number of ticks stored using ``rep``. The representation is unaware of the
+tick period it is being used to represent, but ``timespec`` is setup to assume
+a nanosecond tick period; which is the only case where the names ``tv_sec``
+and ``tv_nsec`` match the values they store.
+
+When we convert a nanosecond duration to seconds, ``fs_timespec_rep`` will
+use ``tv_sec`` to represent the number of giga seconds, and ``tv_nsec`` the
+remaining seconds. Let's consider how this might cause a bug were users allowed
+to manipulate the fields directly.
+
+.. code-block:: cpp
+
+  template <class Period>
+  timespec convert_to_timespec(duration<fs_time_rep, Period> dur) {
+    fs_timespec_rep rep = dur.count();
+    return {rep.tv_sec, rep.tv_nsec}; // Oops! Period may not be nanoseconds.
+  }
+
+  template <class Duration>
+  Duration convert_to_duration(timespec ts) {
+    Duration dur({ts.tv_sec, ts.tv_nsec}); // Oops! Period may not be nanoseconds.
+    return file_time_type(dur);
+    file_time_type tp = last_write_time(p);
+    auto dur =
+  }
+
+  time_t extract_seconds(file_time_type tp) {
+    // Converting to seconds is a silly bug, but I could see it happening.
+    using SecsT = chrono::duration<file_time_type::rep, ratio<1, 1>>;
+    auto secs = duration_cast<Secs>(tp.time_since_epoch());
+    // tv_sec is now representing gigaseconds.
+    return secs.count().tv_sec; // Oops!
+  }
+
+Despite ``fs_timespec_rep`` not being usable in any manner resembling
+``timespec``, it still might buy us our goal of matching its range exactly,
+right?
+
+Sort of. Chrono provides a specialization point which specifies the minimum
+and maximum values for a custom representation. It looks like this:
+
+.. code-block:: cpp
+
+  template <>
+  struct duration_values<fs_timespec_rep> {
+    static fs_timespec_rep zero();
+    static fs_timespec_rep min();
+    static fs_timespec_rep max() { // assume friendship.
+      fs_timespec_rep val;
+      val.tv_sec = numeric_limits<time_t>::max();
+      val.tv_nsec = nano::den - 1;
+      return val;
+    }
+  };
+
+Notice that ``duration_values`` doesn't tell the representation what tick
+period it's actually representing. This would indeed correctly limit the range
+of ``duration<fs_timespec_rep, nano>`` to exactly that of ``timespec``. But
+nanoseconds isn't the only tick period it will be used to represent. For
+example:
+
+.. code-block:: cpp
+
+  void test() {
+    using rep = file_time_type::rep;
+    using fs_nsec = duration<rep, nano>;
+    using fs_sec = duration<rep>;
+    fs_nsec nsecs(fs_seconds::max()); // Truncates
+  }
+
+Though the above example may appear silly, I think it follows from the incorrect
+notion that using a ``timespec`` rep in chrono actually makes it act as if it
+were an actual ``timespec``.
+
+Interactions with 32 bit ``time_t``
+-----------------------------------
+
+Up until now we've only be considering cases where ``time_t`` is 64 bits, but what
+about 32 bit systems/builds where ``time_t`` is 32 bits? (this is the common case
+for 32 bit builds).
+
+When ``time_t`` is 32 bits, we can implement ``file_time_type`` simply using 64-bit
+``long long``. There is no need to get either ``__int128_t`` or ``timespec`` emulation
+involved. And nor should we, as it would suffer from the numerous complications
+described by this paper.
+
+Obviously our implementation for 32-bit builds should act as similarly to the
+64-bit build as possible. Code which compiles in one, should compile in the other.
+This consideration is important when choosing between ``__int128_t`` and
+emulating ``timespec``. The solution which provides the most uniformity with
+the least eccentricity is the preferable one.
+
+Summary
+=======
+
+The ``file_time_type`` time point is used to represent the write times for files.
+Its job is to act as part of a C++ wrapper for less ideal system interfaces. The
+underlying filesystem uses the ``timespec`` struct for the same purpose.
+
+However, the initial implementation of ``file_time_type`` could not represent
+either the range or resolution of ``timespec``, making it unsuitable. Fixing
+this requires an implementation which uses more than 64 bits to store the
+time point.
+
+We primarily considered two solutions: Using ``__int128_t`` and using a
+arithmetic emulation of ``timespec``. Each has its pros and cons, and both
+come with more than one complication.
+
+The Potential Solutions
+-----------------------
+
+``long long`` - The Status Quo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pros:
+
+* As a type ``long long`` plays the nicest with others:
+
+  * It works with streaming operators and other library entities which support
+    builtin integer types, but don't support ``__int128_t``.
+  * Its the representation used by chrono's ``nanosecond`` and ``second`` typedefs.
+
+Cons:
+
+* It cannot provide the same resolution as ``timespec`` unless we limit it
+  to a range of +/- 300 years from the epoch.
+* It cannot provide the same range as ``timespec`` unless we limit its resolution
+  to seconds.
+* ``last_write_time`` has to report an error when the time reported by the filesystem
+  is unrepresentable.
+
+__int128_t
+~~~~~~~~~~~
+
+Pros:
+
+* It is an integer type.
+* It makes the implementation simple and efficient.
+* Acts exactly like other arithmetic types.
+* Can be implicitly converted to a builtin integer type by the user.
+
+  * This is important for doing things like:
+
+    .. code-block:: cpp
+
+      void c_interface_using_time_t(const char* p, time_t);
+
+      void foo(path p) {
+        file_time_type tp = last_write_time(p);
+        time_t secs = duration_cast<seconds>(tp.time_since_epoch()).count();
+        c_interface_using_time_t(p.c_str(), secs);
+      }
+
+Cons:
+
+* It isn't always available (but on 64 bit machines, it normally is).
+* It causes ``file_time_type`` to have a larger range than ``timespec``.
+* It doesn't always act the same as other builtin integer types. For example
+  with ``cout`` or ``to_string``.
+* Allows implicit truncation to 64 bit integers.
+* It can be implicitly converted to a builtin integer type by the user,
+  truncating its value.
+
+Arithmetic ``timespec`` Emulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pros:
+
+* It has the exact same range and resolution of ``timespec`` when representing
+  a nanosecond tick period.
+* It's always available, unlike ``__int128_t``.
+
+Cons:
+
+* It has a larger range when representing any period longer than a nanosecond.
+* Doesn't actually allow users to use it like a ``timespec``.
+* The required representation of using ``tv_sec`` to store the giga tick count
+  and ``tv_nsec`` to store the remainder adds nothing over a 128 bit integer,
+  but complicates a lot.
+* It isn't a builtin integer type, and can't be used anything like one.
+* Chrono can be made to work with it, but not nicely.
+* Emulating arithmetic classes come with their own host of problems regarding
+  overload resolution (Each operator needs three SFINAE constrained versions of
+  it in order to act like builtin integer types).
+* It offers little over simply using ``__int128_t``.
+* It acts the most differently than implementations using an actual integer type,
+  which has a high chance of breaking source compatibility.
+
+
+Selected Solution - Using ``__int128_t``
+=========================================
+
+The solution I selected for libc++ is using ``__int128_t`` when available,
+and otherwise falling back to using ``long long`` with nanosecond precision.
+
+When ``__int128_t`` is available, or when ``time_t`` is 32-bits, the implementation
+provides same resolution and a greater range than ``timespec``. Otherwise
+it still provides the same resolution, but is limited to a range of +/- 300
+years. This final case should be rather rare, as ``__int128_t``
+is normally available in 64-bit builds, and ``time_t`` is normally 32-bits
+during 32-bit builds.
+
+Although falling back to ``long long`` and nanosecond precision is less than
+ideal, it also happens to be the implementation provided by both libstdc++
+and MSVC. (So that makes it better, right?)
+
+Although the ``timespec`` emulation solution is feasible and would largely
+do what we want, it comes with too many complications, potential problems
+and discrepancies when compared to "normal" chrono time points and durations.
+
+An emulation of a builtin arithmetic type using a class is never going to act
+exactly the same, and the difference will be felt by users. It's not reasonable
+to expect them to tolerate and work around these differences. And once
+we commit to an ABI it will be too late to change. Committing to this seems
+risky.
+
+Therefore, ``__int128_t`` seems like the better solution.
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst b/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst
new file mode 100644
index 00000000000..330ce74cf77
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/ThreadingSupportAPI.rst
@@ -0,0 +1,83 @@
+=====================
+Threading Support API
+=====================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ supports using multiple different threading models and configurations
+to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
+These different models provide entirely different interfaces from each
+other. To address this libc++ wraps the underlying threading API in a new and
+consistent API, which it uses internally to implement threading primitives.
+
+The ``<__threading_support>`` header is where libc++ defines its internal
+threading interface. It contains forward declarations of the internal threading
+interface as well as definitions for the interface.
+
+External Threading API and the ``<__external_threading>`` header
+================================================================
+
+In order to support vendors with custom threading API's libc++ allows the
+entire internal threading interface to be provided by an external,
+vendor provided, header.
+
+When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__threading_support>``
+header simply forwards to the ``<__external_threading>`` header (which must exist).
+It is expected that the ``<__external_threading>`` header provide the exact
+interface normally provided by ``<__threading_support>``.
+
+External Threading Library
+==========================
+
+libc++ can be compiled with its internal threading API delegating to an external
+library. Such a configuration is useful for library vendors who wish to
+distribute a thread-agnostic libc++ library, where the users of the library are
+expected to provide the implementation of the libc++ internal threading API.
+
+On a production setting, this would be achieved through a custom
+``<__external_threading>`` header, which declares the libc++ internal threading
+API but leaves out the implementation.
+
+The ``-DLIBCXX_BUILD_EXTERNAL_THREAD_LIBRARY`` option allows building libc++ in
+such a configuration while allowing it to be tested on a platform that supports
+any of the threading systems (e.g. pthread) supported in ``__threading_support``
+header. Therefore, the main purpose of this option is to allow testing of this
+particular configuration of the library without being tied to a vendor-specific
+threading system. This option is only meant to be used by libc++ library
+developers.
+
+Threading Configuration Macros
+==============================
+
+**_LIBCPP_HAS_NO_THREADS**
+  This macro is defined when libc++ is built without threading support. It
+  should not be manually defined by the user.
+
+**_LIBCPP_HAS_THREAD_API_EXTERNAL**
+  This macro is defined when libc++ should use the ``<__external_threading>``
+  header to provide the internal threading API. This macro overrides
+  ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
+
+**_LIBCPP_HAS_THREAD_API_PTHREAD**
+  This macro is defined when libc++ should use POSIX threads to implement the
+  internal threading API.
+
+**_LIBCPP_HAS_THREAD_API_WIN32**
+  This macro is defined when libc++ should use Win32 threads to implement the
+  internal threading API.
+
+**_LIBCPP_HAS_THREAD_LIBRARY_EXTERNAL**
+  This macro is defined when libc++ expects the definitions of the internal
+  threading API to be provided by an external library. When defined
+  ``<__threading_support>`` will only provide the forward declarations and
+  typedefs for the internal threading API.
+
+**_LIBCPP_BUILDING_THREAD_LIBRARY_EXTERNAL**
+  This macro is used to build an external threading library using the
+  ``<__threading_support>``. Specifically it exposes the threading API
+  definitions in ``<__threading_support>`` as non-inline definitions meant to
+  be compiled into a library.
diff --git a/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst b/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst
new file mode 100644
index 00000000000..d0d4f0adb22
--- /dev/null
+++ b/gnu/llvm/libcxx/docs/DesignDocs/VisibilityMacros.rst
@@ -0,0 +1,218 @@
+========================
+Symbol Visibility Macros
+========================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+Libc++ uses various "visibility" macros in order to provide a stable ABI in
+both the library and the headers. These macros work by changing the
+visibility and inlining characteristics of the symbols they are applied to.
+
+Visibility Macros
+=================
+
+**_LIBCPP_HIDDEN**
+  Mark a symbol as hidden so it will not be exported from shared libraries.
+
+**_LIBCPP_FUNC_VIS**
+  Mark a symbol as being exported by the libc++ library. This attribute must
+  be applied to the declaration of all functions exported by the libc++ dylib.
+
+**_LIBCPP_EXPORTED_FROM_ABI**
+  Mark a symbol as being exported by the libc++ library. This attribute may
+  only be applied to objects defined in the libc++ runtime library. On Windows,
+  this macro applies `dllimport`/`dllexport` to the symbol, and on other
+  platforms it gives the symbol default visibility.
+
+**_LIBCPP_OVERRIDABLE_FUNC_VIS**
+  Mark a symbol as being exported by the libc++ library, but allow it to be
+  overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
+  This macro is applied to all `operator new` and `operator delete` overloads.
+
+  **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
+  locally, since `dllimport` indicates the symbol should be bound to a separate
+  DLL. All `operator new` and `operator delete` overloads are required to be
+  locally overridable, and therefore must not be marked `dllimport`. On Windows,
+  this macro therefore expands to `__declspec(dllexport)` when building the
+  library and has an empty definition otherwise.
+
+**_LIBCPP_HIDE_FROM_ABI**
+  Mark a function as not being part of the ABI of any final linked image that
+  uses it.
+
+**_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
+  Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
+  when libc++ is built with an ABI version after ABI v1. This macro is used to
+  maintain ABI compatibility for symbols that have been historically exported
+  by libc++ in v1 of the ABI, but that we don't want to export in the future.
+
+  This macro works as follows. When we build libc++, we either hide the symbol
+  from the ABI (if the symbol is not part of the ABI in the version we're
+  building), or we leave it included. From user code (i.e. when we're not
+  building libc++), the macro always marks symbols as internal so that programs
+  built using new libc++ headers stop relying on symbols that are removed from
+  the ABI in a future version. Each time we release a new stable version of the
+  ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
+  use it to start removing symbols from the ABI after that stable version.
+
+**_LIBCPP_HIDE_FROM_ABI_PER_TU**
+  This macro controls whether symbols hidden from the ABI with `_LIBCPP_HIDE_FROM_ABI`
+  are local to each translation unit in addition to being local to each final
+  linked image. This macro is defined to either 0 or 1. When it is defined to
+  1, translation units compiled with different versions of libc++ can be linked
+  together, since all non ABI-facing functions are local to each translation unit.
+  This allows static archives built with different versions of libc++ to be linked
+  together. This also means that functions marked with `_LIBCPP_HIDE_FROM_ABI`
+  are not guaranteed to have the same address across translation unit boundaries.
+
+  When the macro is defined to 0, there is no guarantee that translation units
+  compiled with different versions of libc++ can interoperate. However, this
+  leads to code size improvements, since non ABI-facing functions can be
+  deduplicated across translation unit boundaries.
+
+  This macro can be defined by users to control the behavior they want from
+  libc++. The default value of this macro (0 or 1) is controlled by whether
+  `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined, which is intended to
+  be used by vendors only (see below).
+
+**_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT**
+  This macro controls the default value for `_LIBCPP_HIDE_FROM_ABI_PER_TU`.
+  When the macro is defined, per TU ABI insulation is enabled by default, and
+  `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 1 unless overridden by users.
+  Otherwise, per TU ABI insulation is disabled by default, and
+  `_LIBCPP_HIDE_FROM_ABI_PER_TU` is defined to 0 unless overridden by users.
+
+  This macro is intended for vendors to control whether they want to ship
+  libc++ with per TU ABI insulation enabled by default. Users can always
+  control the behavior they want by defining `_LIBCPP_HIDE_FROM_ABI_PER_TU`
+  appropriately.
+
+  By default, this macro is not defined, which means that per TU ABI insulation
+  is not provided unless explicitly overridden by users.
+
+**_LIBCPP_TYPE_VIS**
+  Mark a type's typeinfo, vtable and members as having default visibility.
+  This attribute cannot be used on class templates.
+
+**_LIBCPP_TEMPLATE_VIS**
+  Mark a type's typeinfo and vtable as having default visibility.
+  This macro has no effect on the visibility of the type's member functions.
+
+  **GCC Behavior**: GCC does not support Clang's `type_visibility(...)`
+  attribute. With GCC the `visibility(...)` attribute is used and member
+  functions are affected.
+
+  **Windows Behavior**: DLLs do not support dllimport/export on class templates.
+  The macro has an empty definition on this platform.
+
+
+**_LIBCPP_ENUM_VIS**
+  Mark the typeinfo of an enum as having default visibility. This attribute
+  should be applied to all enum declarations.
+
+  **Windows Behavior**: DLLs do not support importing or exporting enumeration
+  typeinfo. The macro has an empty definition on this platform.
+
+  **GCC Behavior**: GCC un-hides the typeinfo for enumerations by default, even
+  if `-fvisibility=hidden` is specified. Additionally applying a visibility
+  attribute to an enum class results in a warning. The macro has an empty
+  definition with GCC.
+
+**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
+  Mark the member functions, typeinfo, and vtable of the type named in
+  a `_LIBCPP_EXTERN_TEMPLATE` declaration as being exported by the libc++ library.
+  This attribute must be specified on all extern class template declarations.
+
+  This macro is used to override the `_LIBCPP_TEMPLATE_VIS` attribute
+  specified on the primary template and to export the member functions produced
+  by the explicit instantiation in the dylib.
+
+  **GCC Behavior**: GCC ignores visibility attributes applied the type in
+  extern template declarations and applying an attribute results in a warning.
+  However since `_LIBCPP_TEMPLATE_VIS` is the same as
+  `__attribute__((visibility("default"))` the visibility is already correct.
+  The macro has an empty definition with GCC.
+
+  **Windows Behavior**: `extern template` and `dllexport` are fundamentally
+  incompatible *on a class template* on Windows; the former suppresses
+  instantiation, while the latter forces it. Specifying both on the same
+  declaration makes the class template be instantiated, which is not desirable
+  inside headers. This macro therefore expands to `dllimport` outside of libc++
+  but nothing inside of it (rather than expanding to `dllexport`); instead, the
+  explicit instantiations themselves are marked as exported. Note that this
+  applies *only* to extern *class* templates. Extern *function* templates obey
+  regular import/export semantics, and applying `dllexport` directly to the
+  extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
+  thing to do for them.
+
+**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
+  Mark the member functions, typeinfo, and vtable of an explicit instantiation
+  of a class template as being exported by the libc++ library. This attribute
+  must be specified on all class template explicit instantiations.
+
+  It is only necessary to mark the explicit instantiation itself (as opposed to
+  the extern template declaration) as exported on Windows, as discussed above.
+  On all other platforms, this macro has an empty definition.
+
+**_LIBCPP_METHOD_TEMPLATE_IMPLICIT_INSTANTIATION_VIS**
+  Mark a symbol as hidden so it will not be exported from shared libraries. This
+  is intended specifically for method templates of either classes marked with
+  `_LIBCPP_TYPE_VIS` or classes with an extern template instantiation
+  declaration marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS`.
+
+  When building libc++ with hidden visibility, we want explicit template
+  instantiations to export members, which is consistent with existing Windows
+  behavior. We also want classes annotated with `_LIBCPP_TYPE_VIS` to export
+  their members, which is again consistent with existing Windows behavior.
+  Both these changes are necessary for clients to be able to link against a
+  libc++ DSO built with hidden visibility without encountering missing symbols.
+
+  An unfortunate side effect, however, is that method templates of classes
+  either marked `_LIBCPP_TYPE_VIS` or with extern template instantiation
+  declarations marked with `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` also get default
+  visibility when instantiated. These methods are often implicitly instantiated
+  inside other libraries which use the libc++ headers, and will therefore end up
+  being exported from those libraries, since those implicit instantiations will
+  receive default visibility. This is not acceptable for libraries that wish to
+  control their visibility, and led to PR30642.
+
+  Consequently, all such problematic method templates are explicitly marked
+  either hidden (via this macro) or inline, so that they don't leak into client
+  libraries. The problematic methods were found by running
+  `bad-visibility-finder <https://github.com/smeenai/bad-visibility-finder>`_
+  against the libc++ headers after making `_LIBCPP_TYPE_VIS` and
+  `_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS` expand to default visibility.
+
+**_LIBCPP_EXCEPTION_ABI**
+  Mark the member functions, typeinfo, and vtable of the type as being exported
+  by the libc++ library. This macro must be applied to all *exception types*.
+  Exception types should be defined directly in namespace `std` and not the
+  versioning namespace. This allows throwing and catching some exception types
+  between libc++ and libstdc++.
+
+**_LIBCPP_INTERNAL_LINKAGE**
+  Mark the affected entity as having internal linkage (i.e. the `static`
+  keyword in C). This is only a best effort: when the `internal_linkage`
+  attribute is not available, we fall back to forcing the function to be
+  inlined, which approximates internal linkage since an externally visible
+  symbol is never generated for that function. This is an internal macro
+  used as an implementation detail by other visibility macros. Never mark
+  a function or a class with this macro directly.
+
+**_LIBCPP_ALWAYS_INLINE**
+  Forces inlining of the function it is applied to. For visibility purposes,
+  this macro is used to make sure that an externally visible symbol is never
+  generated in an object file when the `internal_linkage` attribute is not
+  available. This is an internal macro used by other visibility macros, and
+  it should not be used directly.
+
+Links
+=====
+
+* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
+* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
+* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_