Document LEAK_SANITIZER_IGNORE_OBJECT() more precisely.

third_party/WebKit/Source/wtf/LeakAnnotations.h

 /*
  * Copyright (C) 2013 Google Inc. All rights reserved.
  * Copyright (C) 2013 Samsung Electronics. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met:
  *
  *     * Redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer.
@@ skipping 16 matching lines @@
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef WTF_LeakAnnotations_h
 #define WTF_LeakAnnotations_h
 
 // This file defines macros for working with LeakSanitizer, allowing memory
 // and allocations to be registered as exempted from LSan consideration.
-//
-// LSan exempted memory will be treated as a source of live pointers,
-// i.e. heap objects reachable by following pointers from an exempted
-// object will not be reported as leaks.
-//
+
 #include "wtf/Noncopyable.h"
 #if USE(LEAK_SANITIZER)
 #include "wtf/AddressSanitizer.h"
 #include "wtf/TypeTraits.h"
 #endif
 
 namespace WTF {
 
 #if USE(LEAK_SANITIZER)
 class LeakSanitizerDisabler {
@@ skipping 15 matching lines @@
 // used internal to wtf/, Blink should use LEAK_SANITIZER_DISABLED_SCOPE
 // elsewhere.
 //
 // TODO(sof): once layering rules allow wtf/ to make use of the Oilpan
 // infrastructure, remove this macro.
 #define WTF_INTERNAL_LEAK_SANITIZER_DISABLED_SCOPE \
         WTF::LeakSanitizerDisabler leakSanitizerDisabler; static_cast<void>(0)
 
 // LEAK_SANITIZER_IGNORE_OBJECT(X): the heap object referenced by pointer X
 // will be ignored by LSan.
+//
+// "Ignorance" means that LSan's leak detection pass will not consider the
+// ignored memory chunk as leaking. Furthermore, the LSan reachability
+// pass will not scan an ignored memory chunk for live, reachable pointers.
+// So, should any of the pointers of that ignored chunk not be reachable
+// from elsewhere, they'll be unreachable and thus not be reported as leaking.
+//
+// Notice that LSan will not transitively compute what's reachable from an
+// ignored memory chunk and consider that set as ignored and unreachable.

[haraken, 2015/12/11 09:46:36]

Slightly better: lsan_ignore_object(X) means that LSan ignores the object graph
starting with X. It does not mean that LSan considers the objects reachable from
X are unreachable.

[sof, 2015/12/11 10:03:37]

A bit too brief perhaps? It ignores the object at X, not its object graph.

 #define LEAK_SANITIZER_IGNORE_OBJECT(X) __lsan_ignore_object(X)
 
 // If the object pointed to by the static local is on the Oilpan heap, a strong
 // Persistent<> is created to keep the pointed-to heap object alive. This makes
 // both the Persistent<> and the heap object _reachable_ by LeakSanitizer's leak
 // detection pass. We do not want these intentional leaks to be reported by LSan,
 // hence the static local is registered with Oilpan
 // (see RegisterStaticLocalReference<> below.)
 //
 // Upon Blink shutdown, all the registered statics are released and a final round
@@ skipping 42 matching lines @@
 #define LEAK_SANITIZER_REGISTER_STATIC_LOCAL(Type, Object) WTF::RegisterStaticLocalReference<Type>::registerStatic(Object)
 #else
 #define WTF_INTERNAL_LEAK_SANITIZER_DISABLED_SCOPE
 #define LEAK_SANITIZER_IGNORE_OBJECT
 #define LEAK_SANITIZER_REGISTER_STATIC_LOCAL(Type, Object) Object
 #endif // USE(LEAK_SANITIZER)
 
 } // namespace WTF
 
 #endif // WTF_LeakAnnotations_h