[libcxx-commits] [PATCH] D145628: [ASan][libcxx] A way to turn off annotations for containers with a specific allocator

[Tacet via Phabricator via libcxx-commits]

AdvenamTacet updated this revision to Diff 509236.
AdvenamTacet added a comment.

This update adds missing `template <class T>` in the example.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D145628/new/

https://reviews.llvm.org/D145628

Files:
  libcxx/docs/UsingLibcxx.rst
  libcxx/include/__memory/allocator_traits.h


Index: libcxx/include/__memory/allocator_traits.h
===================================================================
--- libcxx/include/__memory/allocator_traits.h
+++ libcxx/include/__memory/allocator_traits.h
@@ -401,6 +401,19 @@
     : __is_cpp17_move_insertable<_Alloc>
 { };
 
+// ASan choices
+template <class _Alloc>
+struct __asan_annotate_container_with_allocator
+#   if _LIBCPP_CLANG_VER >= 1600
+      : true_type {};
+#   else
+      // TODO LLVM18: Remove the special-casing
+      : false_type {};
+#   endif
+
+template <class _Tp>
+struct __asan_annotate_container_with_allocator<allocator<_Tp>> : true_type {};
+
 #undef _LIBCPP_ALLOCATOR_TRAITS_HAS_XXX
 
 _LIBCPP_END_NAMESPACE_STD
Index: libcxx/docs/UsingLibcxx.rst
===================================================================
--- libcxx/docs/UsingLibcxx.rst
+++ libcxx/docs/UsingLibcxx.rst
@@ -517,3 +517,29 @@
 ``format-string`` and ``wformat-string`` became ``basic_format_string``,
 ``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types
 available in C++20 as an extension.
+
+Turning off ASan annotation in containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable
+`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators. This may be necessary for allocators that access allocated memory.
+
+For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_ instead of disabling annotations altogether.
+
+The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_ with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.
+
+The annotations for a ``user_allocator`` can be disabled like this:
+
+.. code-block:: cpp
+
+  template<class T>
+  struct std::__asan_annotate_container_with_allocator<user_allocator<T>> : false_type {};
+
+Why may I want to turn it off?
+------------------------------
+
+There are a few reasons why you may want to turn off annotations for an allocator.
+Unpoisoning may not be an option, if (for example) you are not maintaining the allocator.
+
+* You are using allocator, which does not call destructor during deallocation.
+* You are aware that memory allocated with an allocator may be accessed, even when unused by container.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D145628.509236.patch
Type: text/x-patch
Size: 2597 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20230329/b2f2b435/attachment.bin>