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