1=========================================== 2Libc++ 20.0.0 (In-Progress) Release Notes 3=========================================== 4 5.. contents:: 6 :local: 7 :depth: 2 8 9Written by the `Libc++ Team <https://libcxx.llvm.org>`_ 10 11.. warning:: 12 13 These are in-progress notes for the upcoming libc++ 20.0.0 release. 14 Release notes for previous releases can be found on 15 `the Download Page <https://releases.llvm.org/download.html>`_. 16 17Introduction 18============ 19 20This document contains the release notes for the libc++ C++ Standard Library, 21part of the LLVM Compiler Infrastructure, release 20.0.0. Here we describe the 22status of libc++ in some detail, including major improvements from the previous 23release and new feature work. For the general LLVM release notes, see `the LLVM 24documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may 25be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. 26 27For more information about libc++, please see the `Libc++ Web Site 28<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_. 29 30Note that if you are reading this file from a Git checkout or the 31main Libc++ web page, this document applies to the *next* release, not 32the current one. To see the release notes for a specific release, please 33see the `releases page <https://llvm.org/releases/>`_. 34 35What's New in Libc++ 20.0.0? 36============================== 37 38The main focus of the libc++ team has been to implement new C++20, C++23, and C++26 features. 39 40Implemented Papers 41------------------ 42 43- P0619R4: Reviewing Deprecated Facilities of C++17 for C++20 (`Github <https://github.com/llvm/llvm-project/issues/99985>`__) 44- P2747R2: ``constexpr`` placement new (`Github <https://github.com/llvm/llvm-project/issues/105427>`__) 45- P2609R3: Relaxing Ranges Just A Smidge (`Github <https://github.com/llvm/llvm-project/issues/105253>`__) 46- P2985R0: A type trait for detecting virtual base classes (`Github <https://github.com/llvm/llvm-project/issues/105432>`__) 47- ``std::jthread`` and ``<stop_token>`` are not guarded behind ``-fexperimental-library`` anymore 48- P2674R1: A trait for implicit lifetime types (`Github <https://github.com/llvm/llvm-project/issues/105259>`__) 49- P0429R9: A Standard ``flat_map`` (`Github <https://github.com/llvm/llvm-project/issues/105190>`__) 50 51Improvements and New Features 52----------------------------- 53 54- The ``lexicographical_compare`` and ``ranges::lexicographical_compare`` algorithms have been optimized for trivially 55 equality comparable types, resulting in a performance improvement of up to 40x. 56 57- The ``_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER`` macro has been added to make ``std::get_temporary_buffer`` and 58 ``std::return_temporary_buffer`` available. 59 60- The ``std::uncaught_exception`` function was marked as deprecated since C++17 and removed since C++20. The 61 ``_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION`` macro has been added to make ``std::uncaught_exception`` 62 available in C++20 and later modes. 63 64- The internal structure ``__compressed_pair`` has been replaced with ``[[no_unique_address]]``, resulting in reduced 65 compile times and smaller debug information as well as better code generation if optimizations are disabled. 66 The Chromium project measured a 5% reduction in object file and debug information size. 67 68- The ``_LIBCPP_ABI_BOUNDED_UNIQUE_PTR`` ABI configuration was added, which allows ``std::unique_ptr<T[]>`` to 69 detect out-of-bounds accesses in certain circumstances. ``std::unique_ptr<T[]>`` can now also detect out-of-bounds 70 accesses for a limited set of types (non-trivially destructible types) when the ABI configuration is disabled. 71 72- The ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY`` ABI configuration was added, which allows storing valid bounds 73 in ``std::array::iterator`` and detecting OOB accesses when the appropriate hardening mode is enabled. 74 75- The ``input_iterator``-pair overload of ``void assign(InputIt, InputIt)`` has been optimized for ``std::vector``, 76 resulting in a performance improvement of up to 2x for trivial element types (e.g., ``std::vector<int>``), and up 77 to 3.4x for non-trivial element types (e.g., ``std::vector<std::vector<int>>``). 78 79- The ``input_iterator``-pair overload of ``iterator insert(const_iterator, InputIt, InputIt)`` has been optimized 80 for ``std::vector``, resulting in a performance improvement of up to 10x for ``std::vector<int>``, and up to 2.3x 81 for ``std::vector<std::vector<int>>``. 82 83- On Windows, ``<system_error>``'s ``std::system_category`` is now distinct from ``std::generic_category``. The behavior 84 on other operating systems is unchanged. 85 86 On Windows -- unlike on Unix systems -- the libc and system APIs use distinct error codes. The libc functions return 87 ``errno.h`` error codes via the ``errno`` global, while Win32 API functions return ``winerror.h`` error codes via 88 ``GetLastError()``. 89 90 The C++ standard's ``std::error_code`` and ``std::error_category`` functionality was designed to support multiple 91 error domains, precisely in order to handle situations such as this. However, libc++ formerly treated 92 ``generic_category()`` and ``system_category()`` as equivalent, even on Windows. It now implements the intended split, 93 where ``system_category`` represents native ``winerror.h`` error codes, and ``generic_category`` represents libc error 94 codes (and, equivalently, ``std::errc::*`` errors). 95 96 This change enables code like ``std::error_code(GetLastError(), std::system_category()) == 97 std::errc::invalid_argument`` to function as desired: constructing an ``error_code`` with the Windows error number in 98 the "system" category, and then mapping it to a generic code with ``error_condition``, for comparison with the 99 ``std::errc`` constant. 100 101 This is an incompatible change: ``std::error_code(ENOSYS, std::system_category()) == 102 std::errc::function_not_supported`` would formerly have returned true, but now returns false on Windows. Code 103 providing a number from the ``errno.h`` domain should be migrated to construct a ``generic_category`` error_code, 104 instead. (E.g., use ``std::error_code(ENOSYS, std::generic_category())``). The new behavior matches MSVC. 105 106- On Windows, the ``std::filesystem`` library now returns the Win32 ``system_category`` error codes, where it's feasible 107 to do so. This allows interrogation and reporting of the original error code, which is useful if multiple Windows 108 errors map to a single generic error (such as with ``std::errc::no_such_file_or_directory``). 109 110 This is also a slightly-incompatible API change: code inspecting the raw integer value from the returned error_code 111 expecting an integer from ``generic_category`` (e.g. ``err.value() == ENOTDIR``) will not work as desired. Instead, 112 such code should use the comparison operators which implicitly handle eror mappings, ``err == 113 std::errc::not_a_directory``, or use ``err.default_error_condition()`` to map to an ``error_condition``, and then test 114 its ``value()`` and ``category()``. 115 116- ``std::stable_sort`` uses radix sort for integral types now, which can improve the performance up to 10 times, depending 117 on type of sorted elements and the initial state of the sorted array. 118 119- Reduced the amount of debug information generated for internal typedefs. This reduces the size of debug builds. 120 121- Added :ref:`hardening mode <hardening>` support for ``forward_list`` and ``bitset``. 122 123Deprecations and Removals 124------------------------- 125 126- The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to 127 enable the safe mode have been removed in LLVM 20. Please use :ref:`support for hardening <using-hardening-modes>` 128 instead. 129 130- Support for the C++20 synchronization library (``<barrier>``, ``<latch>``, ``atomic::wait``, etc.) has been 131 removed in language modes prior to C++20. If you are using these features prior to C++20, you will need to 132 update to ``-std=c++20``. 133 134- The relational operators for ``std::chrono::weekday`` has been removed entirely, and the 135 ``_LIBCPP_ENABLE_REMOVED_WEEKDAY_RELATIONAL_OPERATORS`` macro is now ignored. 136 137- The ``_LIBCPP_ENABLE_REMOVED_ALLOCATOR_CONST`` macro no longer has any effect. ``std::allocator<const T>`` is not 138 supported as an extension anymore, please migrate any code that uses e.g. ``std::vector<const T>`` to be 139 standards conforming. 140 141- Non-conforming member typedefs ``base``, ``iterator``, ``const_iterator``, ``size_type``, ``difference_type``, and 142 ``const_reference`` of ``std::bitset``, and member typedef ``base`` of ``std::forward_list`` and ``std::list`` are 143 removed. Previously, these member typedefs (except ``const_reference``) were private but could cause ambiguity in name 144 lookup. Code that expects such ambiguity will possibly not compile in LLVM 20. 145 146- The function ``__libcpp_verbose_abort()`` is now ``noexcept``, to match ``std::terminate()``. (The combination of 147 ``noexcept`` and ``[[noreturn]]`` has special significance for function effects analysis.) For backwards compatibility, 148 the ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` macro can be defined to make the function non-``noexcept``. That macro 149 will be removed in LLVM 21. 150 151- ``<ccomplex>``, ``<cstdalign>`` (previously missing), ``<cstdbool>``, and ``<ctgmath>`` are deprecated since C++17 as 152 specified by the standard. They, together with ``<ciso646>``, are removed in C++20, but libc++ still provides these 153 headers as an extension and only deprecates them. The ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS`` macro can be defined to 154 suppress deprecation for these headers. 155 156- The ``_LIBCPP_DISABLE_AVAILABILITY`` macro that was used to force-disable availability markup has now been removed. 157 Whether availability markup is used by the library is now solely controlled at configuration-time. 158 159- The pointer safety functions ``declare_reachable``, ``declare_no_pointers``, ``undeclare_no_pointers`` and 160 ``__undeclare_reachable`` have been removed from the library. These functions were never implemented in a non-trivial 161 way, making it very unlikely that any binary depends on them. 162 163- Non-conforming extension ``packaged_task::result_type`` is deprecated. It will be removed in LLVM 21. 164 165Upcoming Deprecations and Removals 166---------------------------------- 167 168LLVM 21 169~~~~~~~ 170 171- The status of the C++03 implementation will be frozen after the LLVM 21 release. This means that starting in LLVM 22, 172 non-critical bug fixes may not be back-ported to C++03, including LWG issues. C++03 is a legacy platform, where most 173 projects are no longer actively maintained. To reduce the amount of fixes required to keep such legacy projects 174 compiling with up-to-date toolchains, libc++ will aim to freeze the status of the headers in C++03 mode to avoid 175 unintended breaking changes. See https://discourse.llvm.org/t/rfc-freezing-c-03-headers-in-libc for more details. 176 177 If you are using C++03 in your project, you should consider moving to a newer version of the Standard to get the most 178 out of libc++. 179 180- The ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` macro will be removed in LLVM 21, making ``std::__libcpp_verbose_abort`` 181 unconditionally ``noexcept``. 182 183- Non-conforming extension ``packaged_task::result_type`` will be removed in LLVM 21. 184 185 186ABI Affecting Changes 187--------------------- 188 189- The ABI breaks for removing undefined behaviour in ``std::forward_list``, ``std::list``, ``std::map``, ``std::set``, 190 ``std::multimap``, ``std::multiset``, ``std::unordered_map``, ``std::unordered_set``, ``std::unordered_multimap`` and 191 ``std::unordered_multiset`` are now applied unconditionally. This only affects fancy pointers which have a different 192 value representation when pointing at the base of an internal node type instead of the type itself. A size or 193 alignment difference is diagnosed, but more subtle ABI breaks may result in unexpected behaviour. 194 195- The internal structure ``__compressed_pair`` has been replaced with ``[[no_unique_address]]``. The ABI impact is: 196 197 - When using the Itanium ABI (most non-MSVC platforms), empty types are now placed at the beginning of the enclosing 198 object instead of where the beginning of the ``__compressed_pair`` subobject was. This is only observable by 199 checking the address of the empty allocator, equality comparator or hasher. 200 - Additionally, using an overaligned empty type as an allocator, comparator or hasher in the associative containers 201 (and only those containers) may result in the container's object object size and data layout changing beyond only 202 the address of the empty member. 203 - When using the MSVC ABI, this change results in some classes having a completely different memory layout, so this is 204 a genuine ABI break. However, the library does not currently guarantee ABI stability on MSVC platforms. 205 206- The localization support base API has been reimplemented, leading to different functions being exported from the 207 libc++ built library on Windows and Windows-like platforms. 208