146035553Spatrick===================== 246035553SpatrickExperimental Features 346035553Spatrick===================== 446035553Spatrick 546035553Spatrick.. contents:: 646035553Spatrick :local: 746035553Spatrick 846035553Spatrick.. _experimental features: 946035553Spatrick 1046035553SpatrickOverview 1146035553Spatrick======== 1246035553Spatrick 1346035553SpatrickLibc++ implements technical specifications (TSes) and ships them as experimental 1446035553Spatrickfeatures that users are free to try out. The goal is to allow getting feedback 1546035553Spatrickon those experimental features. 1646035553Spatrick 1746035553SpatrickHowever, libc++ does not provide the same guarantees about those features as 1846035553Spatrickit does for the rest of the library. In particular, no ABI or API stability 1946035553Spatrickis guaranteed, and experimental features are deprecated once the non-experimental 2046035553Spatrickequivalent has shipped in the library. This document outlines the details of 2146035553Spatrickthat process. 2246035553Spatrick 2346035553SpatrickBackground 2446035553Spatrick========== 2546035553Spatrick 2646035553SpatrickThe "end game" of a Technical Specification (TS) is to have the features in 2746035553Spatrickthere added to a future version of the C++ Standard. When this happens, the TS 2846035553Spatrickcan be retired. Sometimes, only part of at TS is added to the standard, and 2946035553Spatrickthe rest of the features may be incorporated into the next version of the TS. 3046035553Spatrick 3146035553SpatrickAdoption leaves library implementors with two implementations of a feature, 3246035553Spatrickone in namespace ``std``, and the other in namespace ``std::experimental``. 3346035553SpatrickThe first one will continue to evolve (via issues and papers), while the other 3446035553Spatrickwill not. Gradually they will diverge. It's not good for users to have two 3546035553Spatrick(subtly) different implementations of the same functionality in the same library. 3646035553Spatrick 3746035553SpatrickDesign 3846035553Spatrick====== 3946035553Spatrick 4046035553SpatrickWhen a feature is adopted into the main standard, we implement it in namespace 4146035553Spatrick``std``. Once that implementation is complete, we then create a deprecation 4246035553Spatrickwarning for the corresponding experimental feature warning users to move off 4346035553Spatrickof it and to the now-standardized feature. 4446035553Spatrick 4546035553SpatrickThese deprecation warnings are guarded by a macro of the form 4646035553Spatrick``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which 4746035553Spatrickcan be defined by users to disable the deprecation warning. Whenever 4846035553Spatrickpossible, deprecation warnings are put on a per-declaration basis 4946035553Spatrickusing the ``[[deprecated]]`` attribute, which also allows disabling 5046035553Spatrickthe warnings using ``-Wno-deprecated-declarations``. 5146035553Spatrick 5246035553SpatrickAfter **2 releases** of LLVM, the experimental feature is removed completely 5346035553Spatrick(and the deprecation notice too). Using the experimental feature simply becomes 5446035553Spatrickan error. Furthermore, when an experimental header becomes empty due to the 5546035553Spatrickremoval of the corresponding experimental feature, the header is removed. 5646035553SpatrickKeeping the header around creates incorrect assumptions from users and breaks 5746035553Spatrick``__has_include``. 5846035553Spatrick 5946035553Spatrick 6046035553SpatrickStatus of TSes 6146035553Spatrick============== 6246035553Spatrick 6346035553SpatrickLibrary Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__ 6446035553Spatrick--------------------------------------------------------------------------------------------- 6546035553Spatrick 6646035553SpatrickMost (but not all) of the features of the LFTS were accepted into C++17. 6746035553Spatrick 6846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 6946035553Spatrick| Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 7046035553Spatrick+=========+=======================================================+====================+==========================================+=========================+ 7146035553Spatrick| 2.1 | ``uses_allocator construction`` | 5.0 | 7.0 | | 7246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 7346035553Spatrick| 3.1.2 | ``erased_type`` | | n/a | Not part of C++17 | 7446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 7546035553Spatrick| 3.2.1 | ``tuple_size_v`` | 5.0 | 7.0 | Removed | 7646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 7746035553Spatrick| 3.2.2 | ``apply`` | 5.0 | 7.0 | Removed | 7846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 7946035553Spatrick| 3.3.1 | All of the ``_v`` traits in ``<type_traits>`` | 5.0 | 7.0 | Removed | 8046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 8146035553Spatrick| 3.3.2 | ``invocation_type`` and ``raw_invocation_type`` | | n/a | Not part of C++17 | 8246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 8346035553Spatrick| 3.3.3 | Logical operator traits | 5.0 | 7.0 | Removed | 8446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 8546035553Spatrick| 3.3.3 | Detection Idiom | 5.0 | | Only partially in C++17 | 8646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 8746035553Spatrick| 3.4.1 | All of the ``_v`` traits in ``<ratio>`` | 5.0 | 7.0 | Removed | 8846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 8946035553Spatrick| 3.5.1 | All of the ``_v`` traits in ``<chrono>`` | 5.0 | 7.0 | Removed | 9046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 9146035553Spatrick| 3.6.1 | All of the ``_v`` traits in ``<system_error>`` | 5.0 | 7.0 | Removed | 9246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 9346035553Spatrick| 3.7 | ``propagate_const`` | | n/a | Not part of C++17 | 9446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 9546035553Spatrick| 4.2 | Enhancements to ``function`` | Not yet | | | 9646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 9746035553Spatrick| 4.3 | searchers | 7.0 | 9.0 | | 9846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 9946035553Spatrick| 5 | optional | 5.0 | 7.0 | Removed | 10046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 10146035553Spatrick| 6 | ``any`` | 5.0 | 7.0 | Removed | 10246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 10346035553Spatrick| 7 | ``string_view`` | 5.0 | 7.0 | Removed | 10446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 10546035553Spatrick| 8.2.1 | ``shared_ptr`` enhancements | Not yet | Never added | | 10646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 10746035553Spatrick| 8.2.2 | ``weak_ptr`` enhancements | Not yet | Never added | | 10846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 10946035553Spatrick| 8.5 | ``memory_resource`` | Not yet | | | 11046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 11146035553Spatrick| 8.6 | ``polymorphic_allocator`` | Not yet | | | 11246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 11346035553Spatrick| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 | 11446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 11546035553Spatrick| 8.8 | Access to program-wide ``memory_resource`` objects | Not yet | | | 11646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 11746035553Spatrick| 8.9 | Pool resource classes | Not yet | | | 11846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 11946035553Spatrick| 8.10 | ``monotonic_buffer_resource`` | Not yet | | | 12046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 12146035553Spatrick| 8.11 | Alias templates using polymorphic memory resources | Not yet | | | 12246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 12346035553Spatrick| 8.12 | Non-owning pointers | | n/a | Not part of C++17 | 12446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 12546035553Spatrick| 11.2 | ``promise`` | | n/a | Not part of C++17 | 12646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 12746035553Spatrick| 11.3 | ``packaged_task`` | | n/a | Not part of C++17 | 12846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 12946035553Spatrick| 12.2 | ``search`` | 7.0 | 9.0 | | 13046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 13146035553Spatrick| 12.3 | ``sample`` | 5.0 | 7.0 | Removed | 13246035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 13346035553Spatrick| 12.4 | ``shuffle`` | | | Not part of C++17 | 13446035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 13546035553Spatrick| 13.1 | ``gcd`` and ``lcm`` | 5.0 | 7.0 | Removed | 13646035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 13746035553Spatrick| 13.2 | Random number generation | | | Not part of C++17 | 13846035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 13946035553Spatrick| 14 | Reflection Library | | | Not part of C++17 | 14046035553Spatrick+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 14146035553Spatrick 14246035553Spatrick 14346035553Spatrick`FileSystem TS <https://wg21.link/N4100>`__ 14446035553Spatrick------------------------------------------- 14546035553SpatrickThe FileSystem TS was accepted (in totality) for C++17. 146*4bdff4beSrobertThe FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and was 147*4bdff4beSrobertremoved in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0). 14846035553Spatrick 14946035553SpatrickParallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__ 15046035553Spatrick------------------------------------------------------------------------------------ 15146035553SpatrickSome (most) of the Parallelism TS was accepted for C++17. 15246035553SpatrickWe have not yet shipped an implementation of the Parallelism TS. 15346035553Spatrick 15446035553Spatrick`Coroutines TS <https://wg21.link/N4680>`__ 15546035553Spatrick------------------------------------------- 156*4bdff4beSrobertThe Coroutines TS was accepted for C++20. 157*4bdff4beSrobertAn implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``, 158*4bdff4beSrobertand C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental`` 159*4bdff4beSrobertwill be removed in LLVM 16.0. 16046035553Spatrick 16146035553Spatrick`Networking TS <https://wg21.link/N4656>`__ 16246035553Spatrick------------------------------------------- 16346035553SpatrickThe Networking TS is not yet part of a shipping standard. 16446035553SpatrickWe have not yet shipped an implementation of the Networking TS. 16546035553Spatrick 16646035553Spatrick`Ranges TS <https://wg21.link/N4685>`__ 16746035553Spatrick--------------------------------------- 168*4bdff4beSrobertThe Ranges TS was accepted for C++20. 169*4bdff4beSrobertWe will not ship an implementation of the Ranges TS, however we are actively working on 170*4bdff4beSrobertthe implementation of C++20 Ranges. 17146035553Spatrick 17246035553Spatrick`Concepts TS <https://wg21.link/N4641>`__ 17346035553Spatrick----------------------------------------- 174*4bdff4beSrobertThe Concepts TS was accepted for C++20. 175*4bdff4beSrobertWe will not ship an implementation of the Concepts TS, however we are shipping an 176*4bdff4beSrobertimplementation of C++20 Concepts. 17746035553Spatrick 17846035553Spatrick`Concurrency TS <https://wg21.link/P0159>`__ 17946035553Spatrick-------------------------------------------- 18046035553SpatrickThe Concurrency TS was adopted in Kona (2015). 18146035553SpatrickNone of the Concurrency TS was accepted for C++17. 18246035553SpatrickWe have not yet shipped an implementation of the Concurrency TS. 18346035553Spatrick 18446035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 18546035553Spatrick.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes | 18646035553Spatrick.. +=========+=======================================================+====================+==========================================+=========================+ 18746035553Spatrick.. | 2.3 | class template ``future`` | | | | 18846035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 18946035553Spatrick.. | 2.4 | class template ``shared_future`` | | | | 19046035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 19146035553Spatrick.. | 2.5 | class template ``promise`` | | | Only using ``future`` | 19246035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 19346035553Spatrick.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` | 19446035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 19546035553Spatrick.. | 2.7 | function template ``when_all`` | | | Not part of C++17 | 19646035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 19746035553Spatrick.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 | 19846035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 19946035553Spatrick.. | 2.9 | function template ``when_any`` | | | Not part of C++17 | 20046035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 20146035553Spatrick.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 | 20246035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 20346035553Spatrick.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 | 20446035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 20546035553Spatrick.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 | 20646035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 20746035553Spatrick.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 | 20846035553Spatrick.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ 209