209 lines
20 KiB
ReStructuredText
209 lines
20 KiB
ReStructuredText
=====================
|
|
Experimental Features
|
|
=====================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _experimental features:
|
|
|
|
Overview
|
|
========
|
|
|
|
Libc++ implements technical specifications (TSes) and ships them as experimental
|
|
features that users are free to try out. The goal is to allow getting feedback
|
|
on those experimental features.
|
|
|
|
However, libc++ does not provide the same guarantees about those features as
|
|
it does for the rest of the library. In particular, no ABI or API stability
|
|
is guaranteed, and experimental features are deprecated once the non-experimental
|
|
equivalent has shipped in the library. This document outlines the details of
|
|
that process.
|
|
|
|
Background
|
|
==========
|
|
|
|
The "end game" of a Technical Specification (TS) is to have the features in
|
|
there added to a future version of the C++ Standard. When this happens, the TS
|
|
can be retired. Sometimes, only part of at TS is added to the standard, and
|
|
the rest of the features may be incorporated into the next version of the TS.
|
|
|
|
Adoption leaves library implementors with two implementations of a feature,
|
|
one in namespace ``std``, and the other in namespace ``std::experimental``.
|
|
The first one will continue to evolve (via issues and papers), while the other
|
|
will not. Gradually they will diverge. It's not good for users to have two
|
|
(subtly) different implementations of the same functionality in the same library.
|
|
|
|
Design
|
|
======
|
|
|
|
When a feature is adopted into the main standard, we implement it in namespace
|
|
``std``. Once that implementation is complete, we then create a deprecation
|
|
warning for the corresponding experimental feature warning users to move off
|
|
of it and to the now-standardized feature.
|
|
|
|
These deprecation warnings are guarded by a macro of the form
|
|
``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_<FEATURE>``, which
|
|
can be defined by users to disable the deprecation warning. Whenever
|
|
possible, deprecation warnings are put on a per-declaration basis
|
|
using the ``[[deprecated]]`` attribute, which also allows disabling
|
|
the warnings using ``-Wno-deprecated-declarations``.
|
|
|
|
After **2 releases** of LLVM, the experimental feature is removed completely
|
|
(and the deprecation notice too). Using the experimental feature simply becomes
|
|
an error. Furthermore, when an experimental header becomes empty due to the
|
|
removal of the corresponding experimental feature, the header is removed.
|
|
Keeping the header around creates incorrect assumptions from users and breaks
|
|
``__has_include``.
|
|
|
|
|
|
Status of TSes
|
|
==============
|
|
|
|
Library Fundamentals TS `V1 <https://wg21.link/N4480>`__ and `V2 <https://wg21.link/N4617>`__
|
|
---------------------------------------------------------------------------------------------
|
|
|
|
Most (but not all) of the features of the LFTS were accepted into C++17.
|
|
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes |
|
|
+=========+=======================================================+====================+==========================================+=========================+
|
|
| 2.1 | ``uses_allocator construction`` | 5.0 | 7.0 | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.1.2 | ``erased_type`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.2.1 | ``tuple_size_v`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.2.2 | ``apply`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.3.1 | All of the ``_v`` traits in ``<type_traits>`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.3.2 | ``invocation_type`` and ``raw_invocation_type`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.3.3 | Logical operator traits | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.3.3 | Detection Idiom | 5.0 | | Only partially in C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.4.1 | All of the ``_v`` traits in ``<ratio>`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.5.1 | All of the ``_v`` traits in ``<chrono>`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.6.1 | All of the ``_v`` traits in ``<system_error>`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 3.7 | ``propagate_const`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 4.2 | Enhancements to ``function`` | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 4.3 | searchers | 7.0 | 9.0 | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 5 | optional | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 6 | ``any`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 7 | ``string_view`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.2.1 | ``shared_ptr`` enhancements | Not yet | Never added | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.2.2 | ``weak_ptr`` enhancements | Not yet | Never added | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.5 | ``memory_resource`` | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.6 | ``polymorphic_allocator`` | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.8 | Access to program-wide ``memory_resource`` objects | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.9 | Pool resource classes | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.10 | ``monotonic_buffer_resource`` | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.11 | Alias templates using polymorphic memory resources | Not yet | | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.12 | Non-owning pointers | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 11.2 | ``promise`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 11.3 | ``packaged_task`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 12.2 | ``search`` | 7.0 | 9.0 | |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 12.3 | ``sample`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 12.4 | ``shuffle`` | | | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 13.1 | ``gcd`` and ``lcm`` | 5.0 | 7.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 13.2 | Random number generation | | | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 14 | Reflection Library | | | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
|
|
|
|
`FileSystem TS <https://wg21.link/N4100>`__
|
|
-------------------------------------------
|
|
The FileSystem TS was accepted (in totality) for C++17.
|
|
The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and was
|
|
removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).
|
|
|
|
Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__
|
|
------------------------------------------------------------------------------------
|
|
Some (most) of the Parallelism TS was accepted for C++17.
|
|
We have not yet shipped an implementation of the Parallelism TS.
|
|
|
|
`Coroutines TS <https://wg21.link/N4680>`__
|
|
-------------------------------------------
|
|
The Coroutines TS was accepted for C++20.
|
|
An implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``,
|
|
and C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental``
|
|
will be removed in LLVM 16.0.
|
|
|
|
`Networking TS <https://wg21.link/N4656>`__
|
|
-------------------------------------------
|
|
The Networking TS is not yet part of a shipping standard.
|
|
We have not yet shipped an implementation of the Networking TS.
|
|
|
|
`Ranges TS <https://wg21.link/N4685>`__
|
|
---------------------------------------
|
|
The Ranges TS was accepted for C++20.
|
|
We will not ship an implementation of the Ranges TS, however we are actively working on
|
|
the implementation of C++20 Ranges.
|
|
|
|
`Concepts TS <https://wg21.link/N4641>`__
|
|
-----------------------------------------
|
|
The Concepts TS was accepted for C++20.
|
|
We will not ship an implementation of the Concepts TS, however we are shipping an
|
|
implementation of C++20 Concepts.
|
|
|
|
`Concurrency TS <https://wg21.link/P0159>`__
|
|
--------------------------------------------
|
|
The Concurrency TS was adopted in Kona (2015).
|
|
None of the Concurrency TS was accepted for C++17.
|
|
We have not yet shipped an implementation of the Concurrency TS.
|
|
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | Section | Feature | Shipped in ``std`` | To be removed from ``std::experimental`` | Notes |
|
|
.. +=========+=======================================================+====================+==========================================+=========================+
|
|
.. | 2.3 | class template ``future`` | | | |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.4 | class template ``shared_future`` | | | |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.5 | class template ``promise`` | | | Only using ``future`` |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.6 | class template ``packaged_task`` | | | Only using ``future`` |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.7 | function template ``when_all`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.8 | class template ``when_any_result`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.9 | function template ``when_any`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.10 | function template ``make_ready_future`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 2.11 | function template ``make_exeptional_future`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 3 | ``latches`` and ``barriers`` | | | Not part of C++17 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
.. | 4 | Atomic Smart Pointers | | | Adopted for C++20 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|