| # Experimental Features |
| |
| :::{contents} |
| :local: true |
| ::: |
| |
| (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 | |
| |
| % +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+ |
