1 ===================== 2 Experimental Features 3 ===================== 4 5 .. contents:: 6 :local: 7 8 .. _experimental features: 9 10 Overview 11 ======== 12 13 Libc++ implements technical specifications (TSes) and ships them as experimental 14 features that users are free to try out. The goal is to allow getting feedback 15 on those experimental features. 16 17 However, libc++ does not provide the same guarantees about those features as 18 it does for the rest of the library. In particular, no ABI or API stability 19 is guaranteed, and experimental features are deprecated once the non-experimental 20 equivalent has shipped in the library. This document outlines the details of 21 that process. 22 23 Background 24 ========== 25 26 The "end game" of a Technical Specification (TS) is to have the features in 27 there added to a future version of the C++ Standard. When this happens, the TS 28 can be retired. Sometimes, only part of at TS is added to the standard, and 29 the rest of the features may be incorporated into the next version of the TS. 30 31 Adoption leaves library implementors with two implementations of a feature, 32 one in namespace ``std``, and the other in namespace ``std::experimental``. 33 The first one will continue to evolve (via issues and papers), while the other 34 will 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 37 Design 38 ====== 39 40 When 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 42 warning for the corresponding experimental feature warning users to move off 43 of it and to the now-standardized feature. 44 45 These deprecation warnings are guarded by a macro of the form 46 ``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which 47 can be defined by users to disable the deprecation warning. Whenever 48 possible, deprecation warnings are put on a per-declaration basis 49 using the ``[[deprecated]]`` attribute, which also allows disabling 50 the warnings using ``-Wno-deprecated-declarations``. 51 52 After **2 releases** of LLVM, the experimental feature is removed completely 53 (and the deprecation notice too). Using the experimental feature simply becomes 54 an error. Furthermore, when an experimental header becomes empty due to the 55 removal of the corresponding experimental feature, the header is removed. 56 Keeping the header around creates incorrect assumptions from users and breaks 57 ``__has_include``. 58 59 60 Status of TSes 61 ============== 62 63 Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__ 64 --------------------------------------------------------------------------------------------- 65 66 Most (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 ------------------------------------------- 145 The FileSystem TS was accepted (in totality) for C++17. 146 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). 147 148 Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ 149 ------------------------------------------------------------------------------------ 150 Some (most) of the Parallelism TS was accepted for C++17. 151 We have not yet shipped an implementation of the Parallelism TS. 152 153 `Coroutines TS <https://wg21.link/N4680>`__ 154 ------------------------------------------- 155 The Coroutines TS is not yet part of a shipping standard. 156 We 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 ------------------------------------------- 160 The Networking TS is not yet part of a shipping standard. 161 We have not yet shipped an implementation of the Networking TS. 162 163 `Ranges TS <https://wg21.link/N4685>`__ 164 --------------------------------------- 165 The Ranges TS is not yet part of a shipping standard. 166 We have not yet shipped an implementation of the Ranges TS. 167 168 `Concepts TS <https://wg21.link/N4641>`__ 169 ----------------------------------------- 170 The Concepts TS is not yet part of a shipping standard, but it has been adopted into the C++20 working draft. 171 We have not yet shipped an implementation of the Concepts TS. 172 173 `Concurrency TS <https://wg21.link/P0159>`__ 174 -------------------------------------------- 175 The Concurrency TS was adopted in Kona (2015). 176 None of the Concurrency TS was accepted for C++17. 177 We 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
Indexes created Sun Oct 25 00:26:45 UTC 2026