[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
Cr-Mirrored-From: sso://chromium.googlesource.com/_direct/external/github.com/llvm/llvm-project
Cr-Mirrored-Commit: 776acf225b371b4f4623751a3de8c2d3d324473c
diff --git a/docs/DesignDocs/ExperimentalFeatures.rst b/docs/DesignDocs/ExperimentalFeatures.rst
new file mode 100644
index 0000000..2241496
--- /dev/null
+++ b/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/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index ef3023e..56c98af 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -84,6 +84,9 @@
* The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
library will not remain compatible between versions.
* No guarantees of API or ABI stability are provided.
+ * When we implement the standardized version of an experimental feature,
+ the experimental feature is removed two releases after the non-experimental
+ version has shipped. The full policy is explained :ref:`here <experimental features>`.
Using libc++ on Linux
=====================
diff --git a/docs/index.rst b/docs/index.rst
index 933d0fe..37b278f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -137,6 +137,7 @@
DesignDocs/DebugMode
DesignDocs/CapturingConfigInfo
DesignDocs/ABIVersioning
+ DesignDocs/ExperimentalFeatures
DesignDocs/VisibilityMacros
DesignDocs/ThreadingSupportAPI
DesignDocs/FileTimeType