[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 505722.
AdvenamTacet marked an inline comment as done.
AdvenamTacet added a comment.
Herald added a subscriber: mikhail.ramalho.

This update adds examples how to turn off annotations in a simple way.

I was also thinking about creating a macro `_LIBCPP_ASAN_ANNOTATE_CONTAINER_WITH_ALLOCATOR`, but I don't fully like that idea.
Let me know if you think it's a good change.

  #define _LIBCPP_ASAN_ANNOTATE_CONTAINER_WITH_ALLOCATOR(ALLOC, VALUE) template <class T> \
      struct __asan_annotate_container_with_allocator< ALLOC<T> > { \
          static bool const value = VALUE; \
      };

Then description would be:

  For simple allocators with only one template parameter, it's possible to use
  ``_LIBCPP_ASAN_ANNOTATE_CONTAINER_WITH_ALLOCATOR`` macro.
  
  .. code-block:: cpp
  
    _LIBCPP_ASAN_ANNOTATE_CONTAINER_WITH_ALLOCATOR(user_allocator, false);


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,12 @@
     : __is_cpp17_move_insertable<_Alloc>
 { };
 
+// ASan choices
+template <class _Alloc>
+struct __asan_annotate_container_with_allocator {
+    static bool const value = true;
+};
+
 #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,36 @@
 ``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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Struct template ``__asan_annotate_container_with_allocator`` may be used to turn off ASan annotations for containers
+with a specific allocator.
+If ``__asan_annotate_container_with_allocator<_Alloc>::value == false``, container won't be poisoned at all.
+Value may be changed by template specialization. Variable ``value`` is of type ``bool``.
+
+If you are creating allocator not working correctly with container annotations from libc++,
+a better choice may be unpoisoning memory, if possible. This way, ASan benefits are present in the program.
+
+If one wants to turn off annotations for a simple ``user_allocator`` with one template argument,
+one may do a specialization like below:
+
+.. code-block:: cpp
+
+  template <class T>
+  struct std::__asan_annotate_container_with_allocator<user_allocator<T>> {
+    static bool const value = false;
+  };
+
+It is possible to turn off annotations only for buffers of a specific type (``user_type``),
+allocated with ``user_allocator``.
+
+.. code-block:: cpp
+
+  template <>
+  struct std::__asan_annotate_container_with_allocator<user_allocator<user_type>> {
+    static bool const value = false;
+  };
+
+Changing ``value`` to ``true`` will explicitly turn on annotations, when compiled with ASan.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D145628.505722.patch
Type: text/x-patch
Size: 2211 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20230316/3941bee0/attachment.bin>