1776acf22SLouis Dionne===================== 2776acf22SLouis DionneExperimental Features 3776acf22SLouis Dionne===================== 4776acf22SLouis Dionne 5776acf22SLouis Dionne.. contents:: 6776acf22SLouis Dionne :local: 7776acf22SLouis Dionne 8776acf22SLouis Dionne.. _experimental features: 9776acf22SLouis Dionne 10776acf22SLouis DionneOverview 11776acf22SLouis Dionne======== 12776acf22SLouis Dionne 13776acf22SLouis DionneLibc++ implements technical specifications (TSes) and ships them as experimental 14776acf22SLouis Dionnefeatures that users are free to try out. The goal is to allow getting feedback 15776acf22SLouis Dionneon those experimental features. 16776acf22SLouis Dionne 17776acf22SLouis DionneHowever, libc++ does not provide the same guarantees about those features as 18776acf22SLouis Dionneit does for the rest of the library. In particular, no ABI or API stability 19776acf22SLouis Dionneis guaranteed, and experimental features are deprecated once the non-experimental 20776acf22SLouis Dionneequivalent has shipped in the library. This document outlines the details of 21776acf22SLouis Dionnethat process. 22776acf22SLouis Dionne 23776acf22SLouis DionneBackground 24776acf22SLouis Dionne========== 25776acf22SLouis Dionne 26776acf22SLouis DionneThe "end game" of a Technical Specification (TS) is to have the features in 27776acf22SLouis Dionnethere added to a future version of the C++ Standard. When this happens, the TS 28776acf22SLouis Dionnecan be retired. Sometimes, only part of at TS is added to the standard, and 29776acf22SLouis Dionnethe rest of the features may be incorporated into the next version of the TS. 30776acf22SLouis Dionne 31776acf22SLouis DionneAdoption leaves library implementors with two implementations of a feature, 32776acf22SLouis Dionneone in namespace ``std``, and the other in namespace ``std::experimental``. 33776acf22SLouis DionneThe first one will continue to evolve (via issues and papers), while the other 34776acf22SLouis Dionnewill not. Gradually they will diverge. It's not good for users to have two 35776acf22SLouis Dionne(subtly) different implementations of the same functionality in the same library. 36776acf22SLouis Dionne 37776acf22SLouis DionneDesign 38776acf22SLouis Dionne====== 39776acf22SLouis Dionne 40776acf22SLouis DionneWhen a feature is adopted into the main standard, we implement it in namespace 41776acf22SLouis Dionne``std``. Once that implementation is complete, we then create a deprecation 42776acf22SLouis Dionnewarning for the corresponding experimental feature warning users to move off 43776acf22SLouis Dionneof it and to the now-standardized feature. 44776acf22SLouis Dionne 45776acf22SLouis DionneThese deprecation warnings are guarded by a macro of the form 46776acf22SLouis Dionne``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which 47776acf22SLouis Dionnecan be defined by users to disable the deprecation warning. Whenever 48776acf22SLouis Dionnepossible, deprecation warnings are put on a per-declaration basis 49776acf22SLouis Dionneusing the ``[[deprecated]]`` attribute, which also allows disabling 50776acf22SLouis Dionnethe warnings using ``-Wno-deprecated-declarations``. 51776acf22SLouis Dionne 52776acf22SLouis DionneAfter **2 releases** of LLVM, the experimental feature is removed completely 53776acf22SLouis Dionne(and the deprecation notice too). Using the experimental feature simply becomes 54776acf22SLouis Dionnean error. Furthermore, when an experimental header becomes empty due to the 55776acf22SLouis Dionneremoval of the corresponding experimental feature, the header is removed. 56776acf22SLouis DionneKeeping the header around creates incorrect assumptions from users and breaks 57776acf22SLouis Dionne``__has_include``. 58776acf22SLouis Dionne 59776acf22SLouis Dionne 60776acf22SLouis DionneStatus of TSes 61776acf22SLouis Dionne============== 62776acf22SLouis Dionne 63776acf22SLouis DionneLibrary Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__ 64776acf22SLouis Dionne--------------------------------------------------------------------------------------------- 65776acf22SLouis Dionne 66776acf22SLouis DionneMost (but not all) of the features of the LFTS were accepted into C++17. 67776acf22SLouis Dionne 68776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 69776acf22SLouis Dionne| Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 70776acf22SLouis Dionne+=========+=======================================================+====================+==========================================+=========================+ 71776acf22SLouis Dionne| 2.1 | ``uses_allocator construction`` | 5.0 | 7.0 | | 72776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 73776acf22SLouis Dionne| 3.1.2 | ``erased_type`` | | n/a | Not part of C++17 | 74776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 75776acf22SLouis Dionne| 3.2.1 | ``tuple_size_v`` | 5.0 | 7.0 | Removed | 76776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 77776acf22SLouis Dionne| 3.2.2 | ``apply`` | 5.0 | 7.0 | Removed | 78776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 79776acf22SLouis Dionne| 3.3.1 | All of the ``_v`` traits in ``<type_traits>`` | 5.0 | 7.0 | Removed | 80776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 81776acf22SLouis Dionne| 3.3.2 | ``invocation_type`` and ``raw_invocation_type`` | | n/a | Not part of C++17 | 82776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 83776acf22SLouis Dionne| 3.3.3 | Logical operator traits | 5.0 | 7.0 | Removed | 84776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 85776acf22SLouis Dionne| 3.3.3 | Detection Idiom | 5.0 | | Only partially in C++17 | 86776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 87776acf22SLouis Dionne| 3.4.1 | All of the ``_v`` traits in ``<ratio>`` | 5.0 | 7.0 | Removed | 88776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 89776acf22SLouis Dionne| 3.5.1 | All of the ``_v`` traits in ``<chrono>`` | 5.0 | 7.0 | Removed | 90776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 91776acf22SLouis Dionne| 3.6.1 | All of the ``_v`` traits in ``<system_error>`` | 5.0 | 7.0 | Removed | 92776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 93776acf22SLouis Dionne| 3.7 | ``propagate_const`` | | n/a | Not part of C++17 | 94776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 95776acf22SLouis Dionne| 4.2 | Enhancements to ``function`` | Not yet | | | 96776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 97776acf22SLouis Dionne| 4.3 | searchers | 7.0 | 9.0 | | 98776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 99776acf22SLouis Dionne| 5 | optional | 5.0 | 7.0 | Removed | 100776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 101776acf22SLouis Dionne| 6 | ``any`` | 5.0 | 7.0 | Removed | 102776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 103776acf22SLouis Dionne| 7 | ``string_view`` | 5.0 | 7.0 | Removed | 104776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 105776acf22SLouis Dionne| 8.2.1 | ``shared_ptr`` enhancements | Not yet | Never added | | 106776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 107776acf22SLouis Dionne| 8.2.2 | ``weak_ptr`` enhancements | Not yet | Never added | | 108776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 109*12bb2910SLouis Dionne| 8.5 | ``memory_resource`` | 16.0 | 18.0 | Removed | 110776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 111*12bb2910SLouis Dionne| 8.6 | ``polymorphic_allocator`` | 16.0 | 18.0 | Removed | 112776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 113776acf22SLouis Dionne| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 | 114776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 115*12bb2910SLouis Dionne| 8.8 | Access to program-wide ``memory_resource`` objects | 16.0 | 18.0 | Removed | 116776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 117*12bb2910SLouis Dionne| 8.9 | Pool resource classes | 16.0 | 18.0 | Removed | 118776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 119*12bb2910SLouis Dionne| 8.10 | ``monotonic_buffer_resource`` | 16.0 | 18.0 | Removed | 120776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 121*12bb2910SLouis Dionne| 8.11 | Alias templates using polymorphic memory resources | 16.0 | 18.0 | Removed | 122776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 123776acf22SLouis Dionne| 8.12 | Non-owning pointers | | n/a | Not part of C++17 | 124776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 125776acf22SLouis Dionne| 11.2 | ``promise`` | | n/a | Not part of C++17 | 126776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 127776acf22SLouis Dionne| 11.3 | ``packaged_task`` | | n/a | Not part of C++17 | 128776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 129776acf22SLouis Dionne| 12.2 | ``search`` | 7.0 | 9.0 | | 130776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 131776acf22SLouis Dionne| 12.3 | ``sample`` | 5.0 | 7.0 | Removed | 132776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 133776acf22SLouis Dionne| 12.4 | ``shuffle`` | | | Not part of C++17 | 134776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 135776acf22SLouis Dionne| 13.1 | ``gcd`` and ``lcm`` | 5.0 | 7.0 | Removed | 136776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 137776acf22SLouis Dionne| 13.2 | Random number generation | | | Not part of C++17 | 138776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 139776acf22SLouis Dionne| 14 | Reflection Library | | | Not part of C++17 | 140776acf22SLouis Dionne+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 141776acf22SLouis Dionne 142776acf22SLouis Dionne 143776acf22SLouis Dionne`FileSystem TS <https://wg21.link/N4100>`__ 144776acf22SLouis Dionne------------------------------------------- 145776acf22SLouis DionneThe FileSystem TS was accepted (in totality) for C++17. 146deb3b555SLouis DionneThe FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and was 147deb3b555SLouis Dionneremoved in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0). 148776acf22SLouis Dionne 149776acf22SLouis DionneParallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ 150776acf22SLouis Dionne------------------------------------------------------------------------------------ 151776acf22SLouis DionneSome (most) of the Parallelism TS was accepted for C++17. 152776acf22SLouis DionneWe have not yet shipped an implementation of the Parallelism TS. 153776acf22SLouis Dionne 154776acf22SLouis Dionne`Coroutines TS <https://wg21.link/N4680>`__ 155776acf22SLouis Dionne------------------------------------------- 156deb3b555SLouis DionneThe Coroutines TS was accepted for C++20. 157deb3b555SLouis DionneAn implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``, 158deb3b555SLouis Dionneand C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental`` 159e5ec498fSLouis Dionnehas been removed in LLVM 17.0. 160776acf22SLouis Dionne 161776acf22SLouis Dionne`Networking TS <https://wg21.link/N4656>`__ 162776acf22SLouis Dionne------------------------------------------- 163776acf22SLouis DionneThe Networking TS is not yet part of a shipping standard. 164776acf22SLouis DionneWe have not yet shipped an implementation of the Networking TS. 165776acf22SLouis Dionne 166776acf22SLouis Dionne`Ranges TS <https://wg21.link/N4685>`__ 167776acf22SLouis Dionne--------------------------------------- 168deb3b555SLouis DionneThe Ranges TS was accepted for C++20. 169deb3b555SLouis DionneWe will not ship an implementation of the Ranges TS, however we are actively working on 170deb3b555SLouis Dionnethe implementation of C++20 Ranges. 171776acf22SLouis Dionne 172776acf22SLouis Dionne`Concepts TS <https://wg21.link/N4641>`__ 173776acf22SLouis Dionne----------------------------------------- 174deb3b555SLouis DionneThe Concepts TS was accepted for C++20. 175deb3b555SLouis DionneWe will not ship an implementation of the Concepts TS, however we are shipping an 176deb3b555SLouis Dionneimplementation of C++20 Concepts. 177776acf22SLouis Dionne 178776acf22SLouis Dionne`Concurrency TS <https://wg21.link/P0159>`__ 179776acf22SLouis Dionne-------------------------------------------- 180776acf22SLouis DionneThe Concurrency TS was adopted in Kona (2015). 181776acf22SLouis DionneNone of the Concurrency TS was accepted for C++17. 182776acf22SLouis DionneWe have not yet shipped an implementation of the Concurrency TS. 183776acf22SLouis Dionne 184776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 185776acf22SLouis Dionne.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 186776acf22SLouis Dionne.. +=========+=======================================================+====================+==========================================+=========================+ 187776acf22SLouis Dionne.. | 2.3 | class template ``future`` | | | | 188776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 189776acf22SLouis Dionne.. | 2.4 | class template ``shared_future`` | | | | 190776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 191776acf22SLouis Dionne.. | 2.5 | class template ``promise`` | | | Only using ``future`` | 192776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 193776acf22SLouis Dionne.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` | 194776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 195776acf22SLouis Dionne.. | 2.7 | function template ``when_all`` | | | Not part of C++17 | 196776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 197776acf22SLouis Dionne.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 | 198776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 199776acf22SLouis Dionne.. | 2.9 | function template ``when_any`` | | | Not part of C++17 | 200776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 201776acf22SLouis Dionne.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 | 202776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 203776acf22SLouis Dionne.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 | 204776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 205776acf22SLouis Dionne.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 | 206776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 207776acf22SLouis Dionne.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 | 208776acf22SLouis Dionne.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 209