[PATCH] D114902: [Attrs] Elaborate on the trivial_abi documentation

[Reid Kleckner via Phabricator via cfe-commits]

rnk created this revision.
rnk added reviewers: aaron.ballman, rjmccall, dblaikie, ahatanak.
rnk requested review of this revision.
Herald added a project: clang.

My team recently answered some questions about the trivial_abi
attribute. This change attempts to distill those answers into
user-focused documentation. The previous documentation is somewhat
technical, and the new documentation tries to focus on documenting when
the attribute is safe to use, and what impact the user should expect to
see from the attribute.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D114902

Files:
  clang/include/clang/Basic/AttrDocs.td


Index: clang/include/clang/Basic/AttrDocs.td
===================================================================
--- clang/include/clang/Basic/AttrDocs.td
+++ clang/include/clang/Basic/AttrDocs.td
@@ -3197,10 +3197,50 @@
 def TrivialABIDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{
-The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
-It instructs the compiler to pass and return the type using the C ABI for the
-underlying type when the type would otherwise be considered non-trivial for the
-purpose of calls.
+The ``trivial_abi`` attribute helps the compiler pass some C++ objects more
+efficiently.
+
+Normally, the compiler must pass records (classes, structs, or unions) with
+non-trivial copy constructors or destructors very carefully. When these methods
+are provided, the compiler can no longer freely copy the bytes of the object
+when it is passed by value. As a result, such objects are typically passed
+indirectly by address. This is usually less efficient for small objects such as
+``std::unique_ptr<T>`` and other smart pointers. Smart pointers are often
+passed by value in performance-sensitive code, so this attribute exists to
+allow the user to mark a C++ class, struct, or union as safe to copy as part of
+a function call.
+
+Instances of ``trivial_abi`` classes are always destroyed in the callee, and
+not the caller. The destructor is not called on the storage allocated for the
+object in the caller. This ensures that calls to constructors and destructors
+are balanced, and that this attribute can safely be applied to
+reference-counting smart pointers.
+
+It is not safe to apply the ``trivial_abi`` attribute to classes with
+constructors that capture pointers to the object or its subobjects (fields and
+bases). Most constructors do not capture interior object pointers, so this
+attribute can be safely applied to many value types. Two unsafe common use
+cases to look out for are:
+
+1. "Small" objects: The small string optimization often requires taking the
+   address of an array field and storing it into a pointer field. This is
+   unsafe, as the interior pointer becomes stale when the object is copied into
+   the callee.
+2. Self-registration: Objects that register themselves into a doubly linked
+   list or side table of live instances cannot use ``trivial_abi``. This
+   pattern can be used to implement debug iterators, for example.
+
+The ``trivial_abi`` attribute changes the ABI of all functions that pass or
+return objects of annotated types by value, so it is not safe to apply to types
+passed across stable ABI boundaries.
+
+The ``trivial_abi`` attribute does **not** guarantee that the marked object
+will be passed in registers. It only disables the logic that causes objects
+that are non-trivial for the purpose of calls to be passed indirectly. The
+remaining rules of the platform's calling convention often require that large
+records be passed indirectly. This attribute is most beneficial for
+pointer-sized records such as smart pointers.
+
 A class annotated with ``trivial_abi`` can have non-trivial destructors or
 copy/move constructors without automatically becoming non-trivial for the
 purposes of calls. For example:


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D114902.391109.patch
Type: text/x-patch
Size: 3255 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20211201/c88efdeb/attachment.bin>