211 lines · plain
1=====================2Experimental Features3=====================4 5.. contents::6 :local:7 8.. _experimental features:9 10Overview11========12 13Libc++ implements technical specifications (TSes) and ships them as experimental14features that users are free to try out. The goal is to allow getting feedback15on those experimental features.16 17However, libc++ does not provide the same guarantees about those features as18it does for the rest of the library. In particular, no ABI or API stability19is guaranteed, and experimental features are deprecated once the non-experimental20equivalent has shipped in the library. This document outlines the details of21that process.22 23Background24==========25 26The "end game" of a Technical Specification (TS) is to have the features in27there added to a future version of the C++ Standard. When this happens, the TS28can be retired. Sometimes, only part of at TS is added to the standard, and29the rest of the features may be incorporated into the next version of the TS.30 31Adoption leaves library implementors with two implementations of a feature,32one in namespace ``std``, and the other in namespace ``std::experimental``.33The first one will continue to evolve (via issues and papers), while the other34will not. Gradually they will diverge. It's not good for users to have two35(subtly) different implementations of the same functionality in the same library.36 37Design38======39 40When a feature is adopted into the main standard, we implement it in namespace41``std``. Once that implementation is complete, we then create a deprecation42warning for the corresponding experimental feature warning users to move off43of it and to the now-standardized feature.44 45These deprecation warnings are guarded by a macro of the form46``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which47can be defined by users to disable the deprecation warning. Whenever48possible, deprecation warnings are put on a per-declaration basis49using the ``[[deprecated]]`` attribute, which also allows disabling50the warnings using ``-Wno-deprecated-declarations``.51 52After **2 releases** of LLVM, the experimental feature is removed completely53(and the deprecation notice too). Using the experimental feature simply becomes54an error. Furthermore, when an experimental header becomes empty due to the55removal of the corresponding experimental feature, the header is removed.56Keeping the header around creates incorrect assumptions from users and breaks57``__has_include``.58 59 60Status of TSes61==============62 63Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__64---------------------------------------------------------------------------------------------65 66Most (but not all) of the features of the LFTS were accepted into C++17.67 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`` | 16.0 | 18.0 | Removed |110+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+111| 8.6 | ``polymorphic_allocator`` | 16.0 | 18.0 | Removed |112+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+113| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 |114+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+115| 8.8 | Access to program-wide ``memory_resource`` objects | 16.0 | 18.0 | Removed |116+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+117| 8.9 | Pool resource classes | 16.0 | 18.0 | Removed |118+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+119| 8.10 | ``monotonic_buffer_resource`` | 16.0 | 18.0 | Removed |120+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+121| 8.11 | Alias templates using polymorphic memory resources | 16.0 | 18.0 | Removed |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+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+141 142 143`FileSystem TS <https://wg21.link/N4100>`__144-------------------------------------------145The FileSystem TS was accepted (in totality) for C++17.146The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and was147removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).148 149Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__150------------------------------------------------------------------------------------151Some (most) of the Parallelism TS was accepted for C++17.152We have not yet shipped an implementation of the Parallelism TS.153 154`Coroutines TS <https://wg21.link/N4680>`__155-------------------------------------------156The Coroutines TS was accepted for C++20.157An implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``,158and C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental``159has been removed in LLVM 17.0.160 161`Networking TS <https://wg21.link/N4656>`__162-------------------------------------------163The Networking TS is not yet part of a shipping standard, and there is discussion around removing it.164Libc++ never shipped an implementation of the Networking TS and does not plan to do so in the future,165unless the C++ Standards Committee expresses a desire to merge the Networking TS into the IS (which is166unlikely at this point).167 168`Ranges TS <https://wg21.link/N4685>`__169---------------------------------------170The Ranges TS was accepted for C++20.171We will not ship an implementation of the Ranges TS, however we are actively working on172the implementation of C++20 Ranges.173 174`Concepts TS <https://wg21.link/N4641>`__175-----------------------------------------176The Concepts TS was accepted for C++20.177We will not ship an implementation of the Concepts TS, however we are shipping an178implementation of C++20 Concepts.179 180`Concurrency TS <https://wg21.link/P0159>`__181--------------------------------------------182The Concurrency TS was adopted in Kona (2015).183None of the Concurrency TS was accepted for C++17.184We have not yet shipped an implementation of the Concurrency TS.185 186.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+187.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes |188.. +=========+=======================================================+====================+==========================================+=========================+189.. | 2.3 | class template ``future`` | | | |190.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+191.. | 2.4 | class template ``shared_future`` | | | |192.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+193.. | 2.5 | class template ``promise`` | | | Only using ``future`` |194.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+195.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` |196.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+197.. | 2.7 | function template ``when_all`` | | | Not part of C++17 |198.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+199.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 |200.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+201.. | 2.9 | function template ``when_any`` | | | Not part of C++17 |202.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+203.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 |204.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+205.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 |206.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+207.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 |208.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+209.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 |210.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+211