vasilito
cb424d7448
verify-patch-sanity.py validates every active recipe .patch has internally- consistent hunk line counts — catching the 'malformed patch at line N' failure at commit/CI/preflight time instead of hours into a cook. This cycle hit that class three times (qtwaylandscanner, sddm, xwayland), each only discovered when cookbook tried to apply the patch. Running it across the repo found 29 latent malformed patches (validated against GNU patch: e.g. relibc/P3-sysv-ipc reproduces 'malformed patch at line 22'). They were harmless only because they sit in vendored recipes (baked, not re- applied) — but would fail on any version-bump re-derivation. --fix recounts the hunk headers (body untouched) and repaired all 29. Wired into build-preflight.sh (Phase 1.0D) and redbear-ci.yml, with a unit test (test-patch-sanity.sh). Skips archived/legacy trees and unvalidatable formats (empty placeholders, bare-@@ git hunks).
211 lines
20 KiB
ReStructuredText
211 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`` | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.6 | ``polymorphic_allocator`` | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.7 | ``resource_adaptor`` | | n/a | Not part of C++17 |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.8 | Access to program-wide ``memory_resource`` objects | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.9 | Pool resource classes | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.10 | ``monotonic_buffer_resource`` | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 8.11 | Alias templates using polymorphic memory resources | 16.0 | 18.0 | Removed |
|
|
+---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|
|
| 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``
|
|
has been removed in LLVM 17.0.
|
|
|
|
`Networking TS <https://wg21.link/N4656>`__
|
|
-------------------------------------------
|
|
The Networking TS is not yet part of a shipping standard, and there is discussion around removing it.
|
|
Libc++ never shipped an implementation of the Networking TS and does not plan to do so in the future,
|
|
unless the C++ Standards Committee expresses a desire to merge the Networking TS into the IS (which is
|
|
unlikely at this point).
|
|
|
|
`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 |
|
|
.. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
|