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 was 147removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0). 148 149Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ 150------------------------------------------------------------------------------------ 151Some (most) of the Parallelism TS was accepted for C++17. 152We have not yet shipped an implementation of the Parallelism TS. 153 154`Coroutines TS <https://wg21.link/N4680>`__ 155------------------------------------------- 156The Coroutines TS was accepted for C++20. 157An implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``, 158and C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental`` 159will be removed in LLVM 16.0. 160 161`Networking TS <https://wg21.link/N4656>`__ 162------------------------------------------- 163The Networking TS is not yet part of a shipping standard. 164We have not yet shipped an implementation of the Networking TS. 165 166`Ranges TS <https://wg21.link/N4685>`__ 167--------------------------------------- 168The Ranges TS was accepted for C++20. 169We will not ship an implementation of the Ranges TS, however we are actively working on 170the implementation of C++20 Ranges. 171 172`Concepts TS <https://wg21.link/N4641>`__ 173----------------------------------------- 174The Concepts TS was accepted for C++20. 175We will not ship an implementation of the Concepts TS, however we are shipping an 176implementation of C++20 Concepts. 177 178`Concurrency TS <https://wg21.link/P0159>`__ 179-------------------------------------------- 180The Concurrency TS was adopted in Kona (2015). 181None of the Concurrency TS was accepted for C++17. 182We have not yet shipped an implementation of the Concurrency TS. 183 184.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 185.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 186.. +=========+=======================================================+====================+==========================================+=========================+ 187.. | 2.3 | class template ``future`` | | | | 188.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 189.. | 2.4 | class template ``shared_future`` | | | | 190.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 191.. | 2.5 | class template ``promise`` | | | Only using ``future`` | 192.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 193.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` | 194.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 195.. | 2.7 | function template ``when_all`` | | | Not part of C++17 | 196.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 197.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 | 198.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 199.. | 2.9 | function template ``when_any`` | | | Not part of C++17 | 200.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 201.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 | 202.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 203.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 | 204.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 205.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 | 206.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 207.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 | 208.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 209