1===================== 2Experimental Features 3===================== 4 5.. contents:: 6 :local: 7 8.. _experimental features: 9 10Overview 11======== 12 13Libc++ implements technical specifications (TSes) and ships them as experimental 14features that users are free to try out. The goal is to allow getting feedback 15on those experimental features. 16 17However, libc++ does not provide the same guarantees about those features as 18it does for the rest of the library. In particular, no ABI or API stability 19is guaranteed, and experimental features are deprecated once the non-experimental 20equivalent has shipped in the library. This document outlines the details of 21that process. 22 23Background 24========== 25 26The "end game" of a Technical Specification (TS) is to have the features in 27there added to a future version of the C++ Standard. When this happens, the TS 28can be retired. Sometimes, only part of at TS is added to the standard, and 29the rest of the features may be incorporated into the next version of the TS. 30 31Adoption leaves library implementors with two implementations of a feature, 32one in namespace ``std``, and the other in namespace ``std::experimental``. 33The first one will continue to evolve (via issues and papers), while the other 34will not. Gradually they will diverge. It's not good for users to have two 35(subtly) different implementations of the same functionality in the same library. 36 37Design 38====== 39 40When a feature is adopted into the main standard, we implement it in namespace 41``std``. Once that implementation is complete, we then create a deprecation 42warning for the corresponding experimental feature warning users to move off 43of it and to the now-standardized feature. 44 45These deprecation warnings are guarded by a macro of the form 46``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which 47can be defined by users to disable the deprecation warning. Whenever 48possible, deprecation warnings are put on a per-declaration basis 49using the ``[[deprecated]]`` attribute, which also allows disabling 50the warnings using ``-Wno-deprecated-declarations``. 51 52After **2 releases** of LLVM, the experimental feature is removed completely 53(and the deprecation notice too). Using the experimental feature simply becomes 54an error. Furthermore, when an experimental header becomes empty due to the 55removal of the corresponding experimental feature, the header is removed. 56Keeping the header around creates incorrect assumptions from users and breaks 57``__has_include``. 58 59 60Status of TSes 61============== 62 63Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__ 64--------------------------------------------------------------------------------------------- 65 66Most (but not all) of the features of the LFTS were accepted into C++17. 67 68+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 69| Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 70+=========+=======================================================+====================+==========================================+=========================+ 71| 2.1 | ``uses_allocator construction`` | 5.0 | 7.0 | | 72+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 73| 3.1.2 | ``erased_type`` | | n/a | Not part of C++17 | 74+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 75| 3.2.1 | ``tuple_size_v`` | 5.0 | 7.0 | Removed | 76+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 77| 3.2.2 | ``apply`` | 5.0 | 7.0 | Removed | 78+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 79| 3.3.1 | All of the ``_v`` traits in ``<type_traits>`` | 5.0 | 7.0 | Removed | 80+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 81| 3.3.2 | ``invocation_type`` and ``raw_invocation_type`` | | n/a | Not part of C++17 | 82+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 83| 3.3.3 | Logical operator traits | 5.0 | 7.0 | Removed | 84+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 85| 3.3.3 | Detection Idiom | 5.0 | | Only partially in C++17 | 86+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 87| 3.4.1 | All of the ``_v`` traits in ``<ratio>`` | 5.0 | 7.0 | Removed | 88+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 89| 3.5.1 | All of the ``_v`` traits in ``<chrono>`` | 5.0 | 7.0 | Removed | 90+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 91| 3.6.1 | All of the ``_v`` traits in ``<system_error>`` | 5.0 | 7.0 | Removed | 92+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 93| 3.7 | ``propagate_const`` | | n/a | Not part of C++17 | 94+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 95| 4.2 | Enhancements to ``function`` | Not yet | | | 96+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 97| 4.3 | searchers | 7.0 | 9.0 | | 98+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 99| 5 | optional | 5.0 | 7.0 | Removed | 100+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 101| 6 | ``any`` | 5.0 | 7.0 | Removed | 102+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 103| 7 | ``string_view`` | 5.0 | 7.0 | Removed | 104+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 105| 8.2.1 | ``shared_ptr`` enhancements | Not yet | Never added | | 106+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 107| 8.2.2 | ``weak_ptr`` enhancements | Not yet | Never added | | 108+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 109| 8.5 | ``memory_resource`` | Not yet | | | 110+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 111| 8.6 | ``polymorphic_allocator`` | Not yet | | | 112+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 113| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 | 114+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 115| 8.8 | Access to program-wide ``memory_resource`` objects | Not yet | | | 116+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 117| 8.9 | Pool resource classes | Not yet | | | 118+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 119| 8.10 | ``monotonic_buffer_resource`` | Not yet | | | 120+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 121| 8.11 | Alias templates using polymorphic memory resources | Not yet | | | 122+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 123| 8.12 | Non-owning pointers | | n/a | Not part of C++17 | 124+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 125| 11.2 | ``promise`` | | n/a | Not part of C++17 | 126+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 127| 11.3 | ``packaged_task`` | | n/a | Not part of C++17 | 128+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 129| 12.2 | ``search`` | 7.0 | 9.0 | | 130+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 131| 12.3 | ``sample`` | 5.0 | 7.0 | Removed | 132+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 133| 12.4 | ``shuffle`` | | | Not part of C++17 | 134+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 135| 13.1 | ``gcd`` and ``lcm`` | 5.0 | 7.0 | Removed | 136+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 137| 13.2 | Random number generation | | | Not part of C++17 | 138+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 139| 14 | Reflection Library | | | Not part of C++17 | 140+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 141 142 143`FileSystem TS <https://wg21.link/N4100>`__ 144------------------------------------------- 145The FileSystem TS was accepted (in totality) for C++17. 146The 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). 147 148Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ 149------------------------------------------------------------------------------------ 150Some (most) of the Parallelism TS was accepted for C++17. 151We have not yet shipped an implementation of the Parallelism TS. 152 153`Coroutines TS <https://wg21.link/N4680>`__ 154------------------------------------------- 155The Coroutines TS is not yet part of a shipping standard. 156We are shipping (as of v5.0) an implementation of the Coroutines TS in namespace ``std::experimental``. 157 158`Networking TS <https://wg21.link/N4656>`__ 159------------------------------------------- 160The Networking TS is not yet part of a shipping standard. 161We have not yet shipped an implementation of the Networking TS. 162 163`Ranges TS <https://wg21.link/N4685>`__ 164--------------------------------------- 165The Ranges TS is not yet part of a shipping standard. 166We have not yet shipped an implementation of the Ranges TS. 167 168`Concepts TS <https://wg21.link/N4641>`__ 169----------------------------------------- 170The Concepts TS is not yet part of a shipping standard, but it has been adopted into the C++20 working draft. 171We have not yet shipped an implementation of the Concepts TS. 172 173`Concurrency TS <https://wg21.link/P0159>`__ 174-------------------------------------------- 175The Concurrency TS was adopted in Kona (2015). 176None of the Concurrency TS was accepted for C++17. 177We have not yet shipped an implementation of the Concurrency TS. 178 179.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 180.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 181.. +=========+=======================================================+====================+==========================================+=========================+ 182.. | 2.3 | class template ``future`` | | | | 183.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 184.. | 2.4 | class template ``shared_future`` | | | | 185.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 186.. | 2.5 | class template ``promise`` | | | Only using ``future`` | 187.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 188.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` | 189.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 190.. | 2.7 | function template ``when_all`` | | | Not part of C++17 | 191.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 192.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 | 193.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 194.. | 2.9 | function template ``when_any`` | | | Not part of C++17 | 195.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 196.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 | 197.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 198.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 | 199.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 200.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 | 201.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 202.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 | 203.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 204