[llvm-branch-commits] [libcxx] [libc++][docs] Convert documentation from reST to Markdown (batch 2) (PR #222064)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Tue Sep 8 14:50:48 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-libcxx
Author: Reid Kleckner (rnk)
<details>
<summary>Changes</summary>
This is the second batch of changes to migrate libc++ documentation from rst to markdown.
I use a local pixel diff tool to compare the rendered HTML, and all diffs seem like fixes. They tend to fall into the following categories:
- dashed bullet lists were previously not rendered, but now they are
- extra indentation interpreted as blockquotes has been removed
- single backticks are now codefont spans, not italic spans
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #<!-- -->222062, which will be a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
-----
Before/after validation links:
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `libcxx/docs/DesignDocs/NoexceptPolicy.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/NoexceptPolicy.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/NoexceptPolicy.html) |
| `libcxx/docs/DesignDocs/PSTLIntegration.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/PSTLIntegration.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/PSTLIntegration.html) |
| `libcxx/docs/DesignDocs/ThreadingSupportAPI.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/ThreadingSupportAPI.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/ThreadingSupportAPI.html) |
| `libcxx/docs/DesignDocs/TimeZone.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/TimeZone.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/TimeZone.html) |
| `libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.html) |
| `libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.html) |
| `libcxx/docs/DesignDocs/VisibilityMacros.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/VisibilityMacros.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/VisibilityMacros.html) |
| `libcxx/docs/DesignDocs/WindowsSupport.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/WindowsSupport.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/WindowsSupport.html) |
| `libcxx/docs/Hardening.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Hardening.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Hardening.html) |
| `libcxx/docs/ImplementationDefinedBehavior.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ImplementationDefinedBehavior.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ImplementationDefinedBehavior.html) |
| `libcxx/docs/Modules.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Modules.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Modules.html) |
| `libcxx/docs/TestingLibcxx.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/TestingLibcxx.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/TestingLibcxx.html) |
| `libcxx/docs/UserDocumentation.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/UserDocumentation.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/UserDocumentation.html) |
| `libcxx/docs/VendorDocumentation.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/VendorDocumentation.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/VendorDocumentation.html) |
| `libcxx/docs/index.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/index.html) |
---
Patch is 230.31 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/222064.diff
15 Files Affected:
- (modified) libcxx/docs/DesignDocs/NoexceptPolicy.md (+4-6)
- (modified) libcxx/docs/DesignDocs/PSTLIntegration.md (+11-12)
- (modified) libcxx/docs/DesignDocs/ThreadingSupportAPI.md (+32-31)
- (modified) libcxx/docs/DesignDocs/TimeZone.md (+41-49)
- (modified) libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md (+85-103)
- (modified) libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md (+31-41)
- (modified) libcxx/docs/DesignDocs/VisibilityMacros.md (+46-43)
- (modified) libcxx/docs/DesignDocs/WindowsSupport.md (+8-12)
- (modified) libcxx/docs/Hardening.md (+311-324)
- (modified) libcxx/docs/ImplementationDefinedBehavior.md (+28-43)
- (modified) libcxx/docs/Modules.md (+218-217)
- (modified) libcxx/docs/TestingLibcxx.md (+337-370)
- (modified) libcxx/docs/UserDocumentation.md (+238-239)
- (modified) libcxx/docs/VendorDocumentation.md (+389-411)
- (modified) libcxx/docs/index.md (+141-159)
``````````diff
diff --git a/libcxx/docs/DesignDocs/NoexceptPolicy.md b/libcxx/docs/DesignDocs/NoexceptPolicy.md
index 74c8ca406ed84..bfefb48d86897 100644
--- a/libcxx/docs/DesignDocs/NoexceptPolicy.md
+++ b/libcxx/docs/DesignDocs/NoexceptPolicy.md
@@ -1,13 +1,11 @@
-===================
-``noexcept`` Policy
-===================
+# `noexcept` Policy
-Extended applications of ``noexcept``
--------------------------------------
+## Extended applications of `noexcept`
As of version 13 libc++ may mark functions that do not throw (i.e.,
-"Throws: Nothing") as ``noexcept``. This has two primary consequences:
+"Throws: Nothing") as `noexcept`. This has two primary consequences:
first, functions might not report precondition violations by throwing.
Second, user-provided functions, such as custom predicates or custom
traits, which throw might not be propagated up to the caller (unless
specified otherwise by the Standard).
+
diff --git a/libcxx/docs/DesignDocs/PSTLIntegration.md b/libcxx/docs/DesignDocs/PSTLIntegration.md
index e2b9e89f050eb..111e5e94953a1 100644
--- a/libcxx/docs/DesignDocs/PSTLIntegration.md
+++ b/libcxx/docs/DesignDocs/PSTLIntegration.md
@@ -1,22 +1,21 @@
-================
-PSTL integration
-================
+# PSTL integration
The PSTL (or Parallel STL) project is quite complex in its current form and does not provide everything that libc++
-requires, for example ``_LIBCPP_HIDE_FROM_ABI`` or similar annotations and including granularized headers. Furthermore,
+requires, for example `_LIBCPP_HIDE_FROM_ABI` or similar annotations and including granularized headers. Furthermore,
the PSTL provides various layers of indirection that make sense in a generic implementation of the parallel algorithms,
but are unnecessarily complex in the context of a single standard library implementation. Because of these drawbacks, we
decided to adopt a modified PSTL in libc++. Specifically, the goals of the modified PSTL are
-- No ``<__pstl_algorithm>`` and similar glue headers -- instead, the implementation files are included directly in
- ``<algorithm>`` and friends.
-- No ``<pstl/internal/algorithm_impl.h>`` and ``<pstl/internal/algorithm_fwd.h>`` headers and friends -- these contain
+- No `<__pstl_algorithm>` and similar glue headers -- instead, the implementation files are included directly in
+ `<algorithm>` and friends.
+- No `<pstl/internal/algorithm_impl.h>` and `<pstl/internal/algorithm_fwd.h>` headers and friends -- these contain
the implementation and forward declarations for internal functions respectively. The implementation lives inside
- ``<__algorithm/pstl_any_of.h>`` and friends, and the forward declarations are not needed inside libc++.
-- No ``<pstl/internal/glue_algorithm_defs.h>`` and ``<pstl/internal/glue_algorithm_impl.h>`` headers and friends --
- these contain the public API. It lives inside ``<__algorithm/pstl_any_of.h>`` and friends instead.
+ `<__algorithm/pstl_any_of.h>` and friends, and the forward declarations are not needed inside libc++.
+- No `<pstl/internal/glue_algorithm_defs.h>` and `<pstl/internal/glue_algorithm_impl.h>` headers and friends --
+ these contain the public API. It lives inside `<__algorithm/pstl_any_of.h>` and friends instead.
- The headers implementing backends are kept with as few changes as possible to make it easier to keep the backends in
sync with the backends from the original PSTL.
-- The configuration headers ``__pstl_config_site.in`` and ``pstl_config.h`` are removed, and any required configuration
- is done inside ``__config_site.in`` and ``__config`` respectively.
+- The configuration headers `__pstl_config_site.in` and `pstl_config.h` are removed, and any required configuration
+ is done inside `__config_site.in` and `__config` respectively.
- libc++-style tests for the public PSTL API
+
diff --git a/libcxx/docs/DesignDocs/ThreadingSupportAPI.md b/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
index d103c49e25952..88894cb8d1416 100644
--- a/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
+++ b/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
@@ -1,37 +1,33 @@
-=====================
-Threading Support API
-=====================
+# Threading Support API
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Overview
-========
+## Overview
Libc++ supports using multiple different threading models and configurations
-to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
+to implement the threading parts of libc++, including `<thread>` and `<mutex>`.
These different models provide entirely different interfaces from each
other. To address this libc++ wraps the underlying threading API in a new and
consistent API, which it uses internally to implement threading primitives.
-The ``<__thread/support.h>`` header is where libc++ defines its internal
+The `<__thread/support.h>` header is where libc++ defines its internal
threading interface. It documents the functions and declarations required
to fullfil the internal threading interface.
-External Threading API and the ``<__external_threading>`` header
-================================================================
+## External Threading API and the `<__external_threading>` header
In order to support vendors with custom threading API's libc++ allows the
entire internal threading interface to be provided by an external,
vendor provided, header.
-When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__thread/support.h>``
-header simply forwards to the ``<__external_threading>`` header (which must exist).
-It is expected that the ``<__external_threading>`` header provide the exact
-interface normally provided by ``<__thread/support.h>``.
+When `_LIBCPP_HAS_THREAD_API_EXTERNAL` is defined the `<__thread/support.h>`
+header simply forwards to the `<__external_threading>` header (which must exist).
+It is expected that the `<__external_threading>` header provide the exact
+interface normally provided by `<__thread/support.h>`.
-External Threading Library
-==========================
+## External Threading Library
libc++ can be compiled with its internal threading API delegating to an external
library. Such a configuration is useful for library vendors who wish to
@@ -39,29 +35,34 @@ distribute a thread-agnostic libc++ library, where the users of the library are
expected to provide the implementation of the libc++ internal threading API.
On a production setting, this would be achieved through a custom
-``<__external_threading>`` header, which declares the libc++ internal threading
+`<__external_threading>` header, which declares the libc++ internal threading
API but leaves out the implementation.
-Threading Configuration Macros
-==============================
+## Threading Configuration Macros
-**_LIBCPP_HAS_THREADS**
- This macro is set to 1 when libc++ is built with threading support. Otherwise
+**\_LIBCPP_HAS_THREADS**
+
+: This macro is set to 1 when libc++ is built with threading support. Otherwise
it is set to 0. It should not be manually defined by the user.
-**_LIBCPP_HAS_THREAD_API_EXTERNAL**
- This macro is defined when libc++ should use the ``<__external_threading>``
+**\_LIBCPP_HAS_THREAD_API_EXTERNAL**
+
+: This macro is defined when libc++ should use the `<__external_threading>`
header to provide the internal threading API. This macro overrides
- ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
+ `_LIBCPP_HAS_THREAD_API_PTHREAD`.
+
+**\_LIBCPP_HAS_THREAD_API_PTHREAD**
-**_LIBCPP_HAS_THREAD_API_PTHREAD**
- This macro is defined when libc++ should use POSIX threads to implement the
+: This macro is defined when libc++ should use POSIX threads to implement the
internal threading API.
-**_LIBCPP_HAS_THREAD_API_C11**
- This macro is defined when libc++ should use C11 threads to implement the
+**\_LIBCPP_HAS_THREAD_API_C11**
+
+: This macro is defined when libc++ should use C11 threads to implement the
internal threading API.
-**_LIBCPP_HAS_THREAD_API_WIN32**
- This macro is defined when libc++ should use Win32 threads to implement the
+**\_LIBCPP_HAS_THREAD_API_WIN32**
+
+: This macro is defined when libc++ should use Win32 threads to implement the
internal threading API.
+
diff --git a/libcxx/docs/DesignDocs/TimeZone.md b/libcxx/docs/DesignDocs/TimeZone.md
index 60adaa4541248..37f47054a9615 100644
--- a/libcxx/docs/DesignDocs/TimeZone.md
+++ b/libcxx/docs/DesignDocs/TimeZone.md
@@ -1,101 +1,92 @@
-=================
-Time Zone Support
-=================
+# Time Zone Support
-Introduction
-============
+## Introduction
-Starting with C++20 the ``<chrono>`` library has support for time zones.
+Starting with C++20 the `<chrono>` library has support for time zones.
These are available in the
-`IANA Time Zone Database <https://data.iana.org/time-zones/tz-link.html>`_.
+[IANA Time Zone Database](https://data.iana.org/time-zones/tz-link.html).
This page describes the design decisions and trade-offs made to implement this
feature. This page contains several links with more information regarding the
contents of the IANA database, this page assumes the reader is familiar with
this information.
-Which version of the Time Zone Database to use
-==============================================
+## Which version of the Time Zone Database to use
The data of the database is available on several platforms in different forms:
- Typically Unix systems ship the database as
- `TZif files <https://www.rfc-editor.org/rfc/rfc8536.html>`_. This format has
- 3 versions and the ``time_zone_link`` information is not always available.
+ [TZif files](https://www.rfc-editor.org/rfc/rfc8536.html). This format has
+ 3 versions and the `time_zone_link` information is not always available.
If available, they are symlinks in the file system.
These files don't provide the database version information. This information
- is needed for the functions ``std::chrono:: remote_version()`` and
- ``std::chrono::reload_tzdb()``.
-
+ is needed for the functions `std::chrono:: remote_version()` and
+ `std::chrono::reload_tzdb()`.
- On several Unix systems the time zone source files are available. These files
are stored in several regions, mainly the continents. This file contains a
large amount of comment with historical information regarding time zones.
The format is documented in the
- `IANA documentation <https://data.iana.org/time-zones/tz-how-to.html>`_
- and in the `man page <https://man7.org/linux/man-pages/man8/zic.8.html>`_ of zic.
+ [IANA documentation](https://data.iana.org/time-zones/tz-how-to.html)
+ and in the [man page](https://man7.org/linux/man-pages/man8/zic.8.html) of zic.
The disadvantage of this version is that at least Linux versions don't have
the database version information. This information is needed for the functions
- ``std::chrono:: remote_version()`` and ``std::chrono::reload_tzdb()``.
-
-- On Linux systems ``tzdata.zi`` is available. This contains the same
+ `std::chrono:: remote_version()` and `std::chrono::reload_tzdb()`.
+- On Linux systems `tzdata.zi` is available. This contains the same
information as the source files but in one file without the comments. This
file uses the same format as the sources, but shortens the names. For example
- ``Rule`` is abbreviated to ``R``. This file contains the database version
+ `Rule` is abbreviated to `R`. This file contains the database version
information.
-The disadvantage of the ``TZif`` format (which is a binary format) is that it's
-not possible to get the proper ``time_zone_link`` information on all platforms.
-The time zone database version number is also missing from ``TZif`` files.
+The disadvantage of the `TZif` format (which is a binary format) is that it's
+not possible to get the proper `time_zone_link` information on all platforms.
+The time zone database version number is also missing from `TZif` files.
Since the time zone database is supposed to contain both these informations,
-``TZif`` files can't be used to create a conforming implementation.
+`TZif` files can't be used to create a conforming implementation.
Since it's easier to parse one file than a set of files we decided
-to use the ``tzdata.zi``. The other benefit is that the ``tzdata.zi`` file
+to use the `tzdata.zi`. The other benefit is that the `tzdata.zi` file
contains the database version information needed for a conforming
implementation.
-The ``tzdata.zi`` file is not available on all platforms as of August 2023, so
+The `tzdata.zi` file is not available on all platforms as of August 2023, so
some vendors will need to make changes to their platform. Most vendors already
ship the database, so they only need to adjust the packaging of their time zone
package to include the files we require. One notable exception is Windows,
where no IANA time zone database is provided at all. However it's possible for
Windows packagers to add these files to their libc++ packages. The IANA
databases can be
-`downloaded <https://data.iana.org/time-zones/releases/>`_.
+[downloaded](https://data.iana.org/time-zones/releases/).
An alternative would be to ship the database with libc++, either as a file or
compiled in the dylib. The text file is about 112 KB. For now libc++ will not
ship this file. If it's hard to get vendors to ship these files we can
reconsider based on that information.
-Leap seconds
-------------
+### Leap seconds
-For the leap seconds libc++ will use the source file ``leap-seconds.list``.
-This file is easier to parse than the ``leapseconds`` file. Both files are
+For the leap seconds libc++ will use the source file `leap-seconds.list`.
+This file is easier to parse than the `leapseconds` file. Both files are
present on Linux, but not always on other platforms. Since these platforms need
-to change their packaging for ``tzdata.zi``, adding two instead of one files
+to change their packaging for `tzdata.zi`, adding two instead of one files
seems a small change.
+## Updating the Time Zone Database
-Updating the Time Zone Database
-===============================
-
-Per `[time.zone.db.remote]/1 <http://eel.is/c++draft/time.zone#db.remote-1>`_
+Per [[time.zone.db.remote]/1](http://eel.is/c++draft/time.zone#db.remote-1)
-.. code-block:: text
-
- The local time zone database is that supplied by the implementation when the
- program first accesses the database, for example via current_zone(). While the
- program is running, the implementation may choose to update the time zone
- database. This update shall not impact the program in any way unless the
- program calls the functions in this subclause. This potentially updated time
- zone database is referred to as the remote time zone database.
+```text
+The local time zone database is that supplied by the implementation when the
+program first accesses the database, for example via current_zone(). While the
+program is running, the implementation may choose to update the time zone
+database. This update shall not impact the program in any way unless the
+program calls the functions in this subclause. This potentially updated time
+zone database is referred to as the remote time zone database.
+```
There is an update mechanism in libc++, however this is not done automatically.
-Invoking the function ``std::chrono::remote_version()`` will parse the version
-information of the ``tzdata.zi`` file and return that information. Similarly,
-``std::chrono::reload_tzdb()`` will parse the ``tzdata.zi`` and
-``leap-seconds.list`` again. This makes it possible to update the database if
+Invoking the function `std::chrono::remote_version()` will parse the version
+information of the `tzdata.zi` file and return that information. Similarly,
+`std::chrono::reload_tzdb()` will parse the `tzdata.zi` and
+`leap-seconds.list` again. This makes it possible to update the database if
needed by the application and gives the user full power over the update policy.
This approach has several advantages:
@@ -107,7 +98,7 @@ This approach has several advantages:
from that task.
- If there is no threading available this polling
becomes more involved. For example, query the file every *x* calls to
- ``std::chrono::get_tzdb()``. This mean calls to ``std::chrono::get_tzdb()``
+ `std::chrono::get_tzdb()`. This mean calls to `std::chrono::get_tzdb()`
would have different performance characteristics.
The small drawback is:
@@ -120,3 +111,4 @@ Another issue with the automatic update is that it may not be considered
Standard compliant, since the Standard uses the wording "This update shall not
impact the program in any way". Using resources could be considered as
impacting the program.
+
diff --git a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
index 1af0b34263662..af65c7bd6e32f 100644
--- a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
+++ b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
@@ -1,149 +1,131 @@
-=============================================
-Enable std::unique_ptr [[clang::trivial_abi]]
-=============================================
+# Enable std::unique_ptr \[[clang::trivial_abi]\]
-Background
-==========
+## Background
Consider the follow snippets
+```cpp
+void raw_func(Foo* raw_arg) { ... }
+void smart_func(std::unique_ptr<Foo> smart_arg) { ... }
-.. code-block:: cpp
+Foo* raw_ptr_retval() { ... }
+std::unique_ptr<Foo*> smart_ptr_retval() { ... }
+```
- void raw_func(Foo* raw_arg) { ... }
- void smart_func(std::unique_ptr<Foo> smart_arg) { ... }
-
- Foo* raw_ptr_retval() { ... }
- std::unique_ptr<Foo*> smart_ptr_retval() { ... }
-
-
-
-The argument ``raw_arg`` could be passed in a register but ``smart_arg`` could not, due to current
+The argument `raw_arg` could be passed in a register but `smart_arg` could not, due to current
implementation.
-Specifically, in the ``smart_arg`` case, the caller secretly constructs a temporary ``std::unique_ptr``
+Specifically, in the `smart_arg` case, the caller secretly constructs a temporary `std::unique_ptr`
in its stack-frame, and then passes a pointer to it to the callee in a hidden parameter.
-Similarly, the return value from ``smart_ptr_retval`` is secretly allocated in the caller and
+Similarly, the return value from `smart_ptr_retval` is secretly allocated in the caller and
passed as a secret reference to the callee.
+## Goal
-Goal
-===================
+`std::unique_ptr` is passed directly in a register.
-``std::unique_ptr`` is passed directly in a register.
-
-Design
-======
-
-* Annotate the two definitions of ``std::unique_ptr`` with ``clang::trivial_abi`` attribute.
-* Put the attribute behind a flag because this change has potential compilation and runtime breakages.
+## Design
+- Annotate the two definitions of `std::unique_ptr` with `clang::trivial_abi` attribute.
+- Put the attribute behind a flag because this change has potential compilation and runtime breakages.
This comes with some side effects:
-* ``std::unique_ptr`` parameters will now be destroyed by callees, rather than callers.
+- `std::unique_ptr` parameters will now be destroyed by callees, rather than callers.
It is worth noting that destruction by callee is not unique to the use of trivial_abi attribute.
In most Microsoft's ABIs, arguments are always destroyed by the callee.
Consequently, this may change the destruction order for function parameters to an order that is non-conforming to the standard.
For example:
+ ```cpp
+ struct A { ~A(); };
+ struct B { ~B(); };
+ struct C { C(A, unique_ptr<B>, A) {} };
+ C c{{}, make_unique<B>, {}};
+ ```
- .. code-block:: cpp
-
- struct A { ~A(); };
- struct B { ~B(); };
- struct C { C(A, unique_ptr<B>, A) {} };
- C c{{}, make_unique<B>, {}};
+ In a conforming implementation, the destruction order for C::C's parameters is required to be `~A(), ~B(), ~A()` but with this mode enabled, we'll instead see `~B(), ~A(), ~A()`.
+- Reduced code-size.
- In a conforming implementation, the destruction order for C::C's parameters is required to be ``~A(), ~B(), ~A()`` but with this mode enabled, we'll instead see ``~B(), ~A(), ~A()``.
-
-* Reduced code-size.
-
-
-Performance impact
-------------------
+### Performance impact
Google has measured performance improvements of up to 1.6% on some large server macrobenchmarks, and a small reduction in binary sizes.
This a...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/222064
More information about the llvm-branch-commits
mailing list