[libcxx-commits] [libcxx] [libc++] Document our ABI guarantees and what ABI flags exist to modify these guarantees (PR #132615)

[Mark de Wever via libcxx-commits]

================
@@ -0,0 +1,199 @@
+=======================
+libc++'s ABI Guarantees
+=======================
+
+libc++ provides multiple types ABI guarantees. These include stability of the layout of structs, the linking of TUs
+built against different versions and configurations of the library, and more. This document describes what guarantees
+libc++ provides in these different fields as well as what options exist for users and vendors to affect these
+guarantees.
+
+Note that all of the guarantees listed below come with an asterisk that there may be circumstances where we deem it
+worth it to break that guarantee. These breaks are communicated to vendors by CCing #libcxx-vendors on GitHub. If you
+are a vendor, please ask to be added to that group to be notified about changes that potentially affect you.
+
+
+Stability of the Layout of Structs
+==================================
+
+The layout of any struct that is observable by the user is kept stable across versions of the library and any options
+users are allowed to change. There are a lot of structs that have internal names, but are none the less observable by
+users; for example through public aliases to these types or because they affect the layout of other types.
+
+There are multiple ABI flags which affect the layout of certain structs:
+
+``_LIBCPP_ABI_ALTERNATE_STRING_LAYOUT``
+---------------------------------------
+This changes the internal layout of ``basic_string`` to move the section that is used for the internal buffer to the
+front, making it eight byte aligned instead of being unaligned, improving the performance of some operations
+significantly.
+
+``_LIBCPP_ABI_NO_ITERATOR_BASES``
+---------------------------------
+This removes the ``std::iterator`` base class from ``back_insert_iterator``, ``front_insert_iterator``,
+``insert_iterator``, ``istream_iterator``, ``ostream_iterator``, ``ostreambuf_itreator``, ``reverse_iterator``, and
+``raw_storage_iterator``. This doesn't directly affect the layout of these types in most cases, but may result in more
+padding being used when they are used in combination, for example ``reverse_iterator<reverse_iterator<T>>``.
+
+- ``_LIBCPP_ABI_VARIANT_INDEX_TYPE_OPTIMIZATION``
+-------------------------------------------------
+This changes the index type used inside ``std::variant`` to the smallest required type to reduce the datasize of
+variants in most cases.
+
+``_LIBCPP_ABI_OPTIMIZED_FUNCTION``
+----------------------------------
+This significantly restructures how `std::function` is written to provide better performance, but is currently not ABI
+stable.
+
+``_LIBCPP_ABI_NO_RANDOM_DEVICE_COMPATIBILITY_LAYOUT``
+-----------------------------------------------------
+This changes the layout of ``std::random_device`` to only holds state with an implementation that gets entropy from a
+file (see ``_LIBCPP_USING_DEV_RANDOM``). When switching from this implementation to another one on a platform that has
+already shipped ``std::random_device``, one needs to retain the same object layout to remain ABI compatible. This flag
+removes these workarounds for platforms that don't care about ABI compatibility.
+
+
+``_LIBCPP_ABI_NO_COMPRESSED_PAIR_PADDING``
+------------------------------------------
+This removes artifical padding from ``_LIBCPP_COMPRESSED_PAIR`` and ``_LIBCPP_COMPRESSED_TRIPLE``. These macros are used
+inside the associative and unordered containers, ``deque``, ``forward_list``, ``future``, ``list``, ``basic_string``,
+``function``, ``shared_ptr``, ``unique_ptr``, and ``vector`` to stay ABI compatible with the legacy
+``__compressed_pair`` type. This has historically been used to reduce storage requirements in the case of empty types,
----------------
mordante wrote:

It seems a bit unclear what `this` refers to.
```suggestion
``__compressed_pair`` type. ``__compressed_pair``  has historically been used to reduce storage requirements in the case of empty types,
```

https://github.com/llvm/llvm-project/pull/132615