| blob | 4cd6bf3a7fcd50dbde806af8855318e8de8afcc5 |
1 =====================
2 Experimental Features
3 =====================
5 .. contents::
6 :local:
8 .. _experimental features:
10 Overview
11 ========
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.
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.
23 Background
24 ==========
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.
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.
37 Design
38 ======
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.
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``.
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``.
60 Status of TSes
61 ==============
63 Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__
64 ---------------------------------------------------------------------------------------------
66 Most (but not all) of the features of the LFTS were accepted into C++17.
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 +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
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 was
147 removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).
149 Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__
150 ------------------------------------------------------------------------------------
151 Some (most) of the Parallelism TS was accepted for C++17.
152 We have not yet shipped an implementation of the Parallelism TS.
154 `Coroutines TS <https://wg21.link/N4680>`__
155 -------------------------------------------
156 The Coroutines TS was accepted for C++20.
157 An implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``,
158 and C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental``
159 has been removed in LLVM 17.0.
161 `Networking TS <https://wg21.link/N4656>`__
162 -------------------------------------------
163 The Networking TS is not yet part of a shipping standard.
164 We have not yet shipped an implementation of the Networking TS.
166 `Ranges TS <https://wg21.link/N4685>`__
167 ---------------------------------------
168 The Ranges TS was accepted for C++20.
169 We will not ship an implementation of the Ranges TS, however we are actively working on
170 the implementation of C++20 Ranges.
172 `Concepts TS <https://wg21.link/N4641>`__
173 -----------------------------------------
174 The Concepts TS was accepted for C++20.
175 We will not ship an implementation of the Concepts TS, however we are shipping an
176 implementation of C++20 Concepts.
178 `Concurrency TS <https://wg21.link/P0159>`__
179 --------------------------------------------
180 The Concurrency TS was adopted in Kona (2015).
181 None of the Concurrency TS was accepted for C++17.
182 We have not yet shipped an implementation of the Concurrency TS.
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 .. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+