chromium之dynamic_annotations

// This file defines dynamic annotations for use with dynamic analysis
// tool such as valgrind, PIN, etc.
//
// Dynamic annotation is a source code annotation that affects
// the generated code (that is, the annotation is not a comment).
// Each such annotation is attached to a particular
// instruction and/or to a particular object (address) in the program.
//
// The annotations that should be used by users are macros in all upper-case
// (e.g., ANNOTATE_NEW_MEMORY).
//
// Actual implementation of these macros may differ depending on the
// dynamic analysis tool being used.
//
// This file supports the following dynamic analysis tools:
// - None (NDEBUG is defined).
//    Macros are defined empty.
// - ThreadSanitizer (NDEBUG is not defined).
//    Macros are defined as calls to non-inlinable empty functions
//    that are intercepted by ThreadSanitizer.
//

// -------------------------------------------------------------
// Annotations useful when implementing condition variables such as CondVar,
// using conditional critical sections (Await/LockWhen) and when constructing
// user-defined synchronization mechanisms.
//
// The annotations ANNOTATE_HAPPENS_BEFORE() and ANNOTATE_HAPPENS_AFTER() can
// be used to define happens-before arcs in user-defined synchronization
// mechanisms:  the race detector will infer an arc from the former to the
// latter when they share the same argument pointer.
//
// Example 1 (reference counting):
//
// void Unref() {
//   ANNOTATE_HAPPENS_BEFORE(&refcount_);
//   if (AtomicDecrementByOne(&refcount_) == 0) {
//     ANNOTATE_HAPPENS_AFTER(&refcount_);
//     delete this;
//   }
// }
//
// Example 2 (message queue):
//
// void MyQueue::Put(Type *e) {
//   MutexLock lock(&mu_);
//   ANNOTATE_HAPPENS_BEFORE(e);
//   PutElementIntoMyQueue(e);
// }
//
// Type *MyQueue::Get() {
//   MutexLock lock(&mu_);
//   Type *e = GetElementFromMyQueue();
//   ANNOTATE_HAPPENS_AFTER(e);
//   return e;
// }
//
// Note: when possible, please use the existing reference counting and message
// queue implementations instead of inventing new ones.