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