[libcxx] Slightly improved policy for handling experimental features

Summary:
Following the discussion on the libcxx-dev mailing list
(http://lists.llvm.org/pipermail/libcxx-dev/2019-May/000358.html),
this implements the new policy for handling experimental features and
their deprecation. We basically add a deprecation warning for
std::experimental::filesystem, and we remove a bunch of <experimental/*>
headers that were now empty.

Reviewers: mclow.lists, EricWF

Subscribers: mgorny, christof, jkorous, dexonsmith, arphaman, libcxx-commits, jfb

Tags: #libc

Differential Revision: https://reviews.llvm.org/D62428

llvm-svn: 363072

1 files changed, 203 insertions, 0 deletions

diff --git a/libcxx/docs/DesignDocs/ExperimentalFeatures.rst b/libcxx/docs/DesignDocs/ExperimentalFeatures.rst
new file mode 100644
index 00000000000..2241496d594
--- /dev/null
+++ b/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       |
+.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+