michael@0: /* Copyright (c) 2011, Google Inc.
michael@0:  * All rights reserved.
michael@0:  *
michael@0:  * Redistribution and use in source and binary forms, with or without
michael@0:  * modification, are permitted provided that the following conditions are
michael@0:  * met:
michael@0:  *
michael@0:  *     * Redistributions of source code must retain the above copyright
michael@0:  * notice, this list of conditions and the following disclaimer.
michael@0:  *     * Neither the name of Google Inc. nor the names of its
michael@0:  * contributors may be used to endorse or promote products derived from
michael@0:  * this software without specific prior written permission.
michael@0:  *
michael@0:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
michael@0:  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
michael@0:  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
michael@0:  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
michael@0:  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@0:  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@0:  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
michael@0:  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
michael@0:  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
michael@0:  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
michael@0:  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
michael@0:  */
michael@0: 
michael@0: /* This file defines dynamic annotations for use with dynamic analysis
michael@0:    tool such as valgrind, PIN, etc.
michael@0: 
michael@0:    Dynamic annotation is a source code annotation that affects
michael@0:    the generated code (that is, the annotation is not a comment).
michael@0:    Each such annotation is attached to a particular
michael@0:    instruction and/or to a particular object (address) in the program.
michael@0: 
michael@0:    The annotations that should be used by users are macros in all upper-case
michael@0:    (e.g., ANNOTATE_NEW_MEMORY).
michael@0: 
michael@0:    Actual implementation of these macros may differ depending on the
michael@0:    dynamic analysis tool being used.
michael@0: 
michael@0:    See http://code.google.com/p/data-race-test/  for more information.
michael@0: 
michael@0:    This file supports the following dynamic analysis tools:
michael@0:    - None (DYNAMIC_ANNOTATIONS_ENABLED is not defined or zero).
michael@0:       Macros are defined empty.
michael@0:    - ThreadSanitizer, Helgrind, DRD (DYNAMIC_ANNOTATIONS_ENABLED is 1).
michael@0:       Macros are defined as calls to non-inlinable empty functions
michael@0:       that are intercepted by Valgrind. */
michael@0: 
michael@0: #ifndef __DYNAMIC_ANNOTATIONS_H__
michael@0: #define __DYNAMIC_ANNOTATIONS_H__
michael@0: 
michael@0: #ifndef DYNAMIC_ANNOTATIONS_PREFIX
michael@0: # define DYNAMIC_ANNOTATIONS_PREFIX
michael@0: #endif
michael@0: 
michael@0: #ifndef DYNAMIC_ANNOTATIONS_PROVIDE_RUNNING_ON_VALGRIND
michael@0: # define DYNAMIC_ANNOTATIONS_PROVIDE_RUNNING_ON_VALGRIND 1
michael@0: #endif
michael@0: 
michael@0: #ifdef DYNAMIC_ANNOTATIONS_WANT_ATTRIBUTE_WEAK
michael@0: # ifdef __GNUC__
michael@0: #  define DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK __attribute__((weak))
michael@0: # else
michael@0: /* TODO(glider): for Windows support we may want to change this macro in order
michael@0:    to prepend __declspec(selectany) to the annotations' declarations. */
michael@0: #  error weak annotations are not supported for your compiler
michael@0: # endif
michael@0: #else
michael@0: # define DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK
michael@0: #endif
michael@0: 
michael@0: /* The following preprocessor magic prepends the value of
michael@0:    DYNAMIC_ANNOTATIONS_PREFIX to annotation function names. */
michael@0: #define DYNAMIC_ANNOTATIONS_GLUE0(A, B) A##B
michael@0: #define DYNAMIC_ANNOTATIONS_GLUE(A, B) DYNAMIC_ANNOTATIONS_GLUE0(A, B)
michael@0: #define DYNAMIC_ANNOTATIONS_NAME(name) \
michael@0:   DYNAMIC_ANNOTATIONS_GLUE(DYNAMIC_ANNOTATIONS_PREFIX, name)
michael@0: 
michael@0: #ifndef DYNAMIC_ANNOTATIONS_ENABLED
michael@0: # define DYNAMIC_ANNOTATIONS_ENABLED 0
michael@0: #endif
michael@0: 
michael@0: #if DYNAMIC_ANNOTATIONS_ENABLED != 0
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful when implementing condition variables such as CondVar,
michael@0:      using conditional critical sections (Await/LockWhen) and when constructing
michael@0:      user-defined synchronization mechanisms.
michael@0: 
michael@0:      The annotations ANNOTATE_HAPPENS_BEFORE() and ANNOTATE_HAPPENS_AFTER() can
michael@0:      be used to define happens-before arcs in user-defined synchronization
michael@0:      mechanisms:  the race detector will infer an arc from the former to the
michael@0:      latter when they share the same argument pointer.
michael@0: 
michael@0:      Example 1 (reference counting):
michael@0: 
michael@0:      void Unref() {
michael@0:        ANNOTATE_HAPPENS_BEFORE(&refcount_);
michael@0:        if (AtomicDecrementByOne(&refcount_) == 0) {
michael@0:          ANNOTATE_HAPPENS_AFTER(&refcount_);
michael@0:          delete this;
michael@0:        }
michael@0:      }
michael@0: 
michael@0:      Example 2 (message queue):
michael@0: 
michael@0:      void MyQueue::Put(Type *e) {
michael@0:        MutexLock lock(&mu_);
michael@0:        ANNOTATE_HAPPENS_BEFORE(e);
michael@0:        PutElementIntoMyQueue(e);
michael@0:      }
michael@0: 
michael@0:      Type *MyQueue::Get() {
michael@0:        MutexLock lock(&mu_);
michael@0:        Type *e = GetElementFromMyQueue();
michael@0:        ANNOTATE_HAPPENS_AFTER(e);
michael@0:        return e;
michael@0:      }
michael@0: 
michael@0:      Note: when possible, please use the existing reference counting and message
michael@0:      queue implementations instead of inventing new ones. */
michael@0: 
michael@0:   /* Report that wait on the condition variable at address "cv" has succeeded
michael@0:      and the lock at address "lock" is held. */
michael@0:   #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarWait)(__FILE__, __LINE__, cv, lock)
michael@0: 
michael@0:   /* Report that wait on the condition variable at "cv" has succeeded.  Variant
michael@0:      w/o lock. */
michael@0:   #define ANNOTATE_CONDVAR_WAIT(cv) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarWait)(__FILE__, __LINE__, cv, NULL)
michael@0: 
michael@0:   /* Report that we are about to signal on the condition variable at address
michael@0:      "cv". */
michael@0:   #define ANNOTATE_CONDVAR_SIGNAL(cv) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarSignal)(__FILE__, __LINE__, cv)
michael@0: 
michael@0:   /* Report that we are about to signal_all on the condition variable at address
michael@0:      "cv". */
michael@0:   #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarSignalAll)(__FILE__, __LINE__, cv)
michael@0: 
michael@0:   /* Annotations for user-defined synchronization mechanisms. */
michael@0:   #define ANNOTATE_HAPPENS_BEFORE(obj) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateHappensBefore)(__FILE__, __LINE__, obj)
michael@0:   #define ANNOTATE_HAPPENS_AFTER(obj) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateHappensAfter)(__FILE__, __LINE__, obj)
michael@0: 
michael@0:   /* DEPRECATED. Don't use it. */
michael@0:   #define ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotatePublishMemoryRange)(__FILE__, __LINE__, \
michael@0:         pointer, size)
michael@0: 
michael@0:   /* DEPRECATED. Don't use it. */
michael@0:   #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateUnpublishMemoryRange)(__FILE__, __LINE__, \
michael@0:         pointer, size)
michael@0: 
michael@0:   /* DEPRECATED. Don't use it. */
michael@0:   #define ANNOTATE_SWAP_MEMORY_RANGE(pointer, size)   \
michael@0:     do {                                              \
michael@0:       ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size); \
michael@0:       ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size);   \
michael@0:     } while (0)
michael@0: 
michael@0:   /* Instruct the tool to create a happens-before arc between mu->Unlock() and
michael@0:      mu->Lock(). This annotation may slow down the race detector and hide real
michael@0:      races. Normally it is used only when it would be difficult to annotate each
michael@0:      of the mutex's critical sections individually using the annotations above.
michael@0:      This annotation makes sense only for hybrid race detectors. For pure
michael@0:      happens-before detectors this is a no-op. For more details see
michael@0:      http://code.google.com/p/data-race-test/wiki/PureHappensBeforeVsHybrid . */
michael@0:   #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateMutexIsUsedAsCondVar)(__FILE__, __LINE__, \
michael@0:         mu)
michael@0: 
michael@0:   /* Opposite to ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX.
michael@0:      Instruct the tool to NOT create h-b arcs between Unlock and Lock, even in
michael@0:      pure happens-before mode. For a hybrid mode this is a no-op. */
michael@0:   #define ANNOTATE_NOT_HAPPENS_BEFORE_MUTEX(mu) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateMutexIsNotPHB)(__FILE__, __LINE__, mu)
michael@0: 
michael@0:   /* Deprecated. Use ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX. */
michael@0:   #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateMutexIsUsedAsCondVar)(__FILE__, __LINE__, \
michael@0:         mu)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful when defining memory allocators, or when memory that
michael@0:      was protected in one way starts to be protected in another. */
michael@0: 
michael@0:   /* Report that a new memory at "address" of size "size" has been allocated.
michael@0:      This might be used when the memory has been retrieved from a free list and
michael@0:      is about to be reused, or when a the locking discipline for a variable
michael@0:      changes. */
michael@0:   #define ANNOTATE_NEW_MEMORY(address, size) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateNewMemory)(__FILE__, __LINE__, address, \
michael@0:         size)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful when defining FIFO queues that transfer data between
michael@0:      threads. */
michael@0: 
michael@0:   /* Report that the producer-consumer queue (such as ProducerConsumerQueue) at
michael@0:      address "pcq" has been created.  The ANNOTATE_PCQ_* annotations
michael@0:      should be used only for FIFO queues.  For non-FIFO queues use
michael@0:      ANNOTATE_HAPPENS_BEFORE (for put) and ANNOTATE_HAPPENS_AFTER (for get). */
michael@0:   #define ANNOTATE_PCQ_CREATE(pcq) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQCreate)(__FILE__, __LINE__, pcq)
michael@0: 
michael@0:   /* Report that the queue at address "pcq" is about to be destroyed. */
michael@0:   #define ANNOTATE_PCQ_DESTROY(pcq) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQDestroy)(__FILE__, __LINE__, pcq)
michael@0: 
michael@0:   /* Report that we are about to put an element into a FIFO queue at address
michael@0:      "pcq". */
michael@0:   #define ANNOTATE_PCQ_PUT(pcq) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQPut)(__FILE__, __LINE__, pcq)
michael@0: 
michael@0:   /* Report that we've just got an element from a FIFO queue at address
michael@0:      "pcq". */
michael@0:   #define ANNOTATE_PCQ_GET(pcq) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQGet)(__FILE__, __LINE__, pcq)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations that suppress errors.  It is usually better to express the
michael@0:      program's synchronization using the other annotations, but these can
michael@0:      be used when all else fails. */
michael@0: 
michael@0:   /* Report that we may have a benign race at "pointer", with size
michael@0:      "sizeof(*(pointer))". "pointer" must be a non-void* pointer.  Insert at the
michael@0:      point where "pointer" has been allocated, preferably close to the point
michael@0:      where the race happens.  See also ANNOTATE_BENIGN_RACE_STATIC. */
michael@0:   #define ANNOTATE_BENIGN_RACE(pointer, description) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBenignRaceSized)(__FILE__, __LINE__, \
michael@0:         pointer, sizeof(*(pointer)), description)
michael@0: 
michael@0:   /* Same as ANNOTATE_BENIGN_RACE(address, description), but applies to
michael@0:      the memory range [address, address+size). */
michael@0:   #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBenignRaceSized)(__FILE__, __LINE__, \
michael@0:         address, size, description)
michael@0: 
michael@0:   /* Request the analysis tool to ignore all reads in the current thread
michael@0:      until ANNOTATE_IGNORE_READS_END is called.
michael@0:      Useful to ignore intentional racey reads, while still checking
michael@0:      other reads and all writes.
michael@0:      See also ANNOTATE_UNPROTECTED_READ. */
michael@0:   #define ANNOTATE_IGNORE_READS_BEGIN() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreReadsBegin)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* Stop ignoring reads. */
michael@0:   #define ANNOTATE_IGNORE_READS_END() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreReadsEnd)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */
michael@0:   #define ANNOTATE_IGNORE_WRITES_BEGIN() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreWritesBegin)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* Stop ignoring writes. */
michael@0:   #define ANNOTATE_IGNORE_WRITES_END() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreWritesEnd)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* Start ignoring all memory accesses (reads and writes). */
michael@0:   #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
michael@0:     do {\
michael@0:       ANNOTATE_IGNORE_READS_BEGIN();\
michael@0:       ANNOTATE_IGNORE_WRITES_BEGIN();\
michael@0:     }while(0)\
michael@0: 
michael@0:   /* Stop ignoring all memory accesses. */
michael@0:   #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \
michael@0:     do {\
michael@0:       ANNOTATE_IGNORE_WRITES_END();\
michael@0:       ANNOTATE_IGNORE_READS_END();\
michael@0:     }while(0)\
michael@0: 
michael@0:   /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore synchronization events:
michael@0:      RWLOCK* and CONDVAR*. */
michael@0:   #define ANNOTATE_IGNORE_SYNC_BEGIN() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreSyncBegin)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* Stop ignoring sync events. */
michael@0:   #define ANNOTATE_IGNORE_SYNC_END() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreSyncEnd)(__FILE__, __LINE__)
michael@0: 
michael@0: 
michael@0:   /* Enable (enable!=0) or disable (enable==0) race detection for all threads.
michael@0:      This annotation could be useful if you want to skip expensive race analysis
michael@0:      during some period of program execution, e.g. during initialization. */
michael@0:   #define ANNOTATE_ENABLE_RACE_DETECTION(enable) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateEnableRaceDetection)(__FILE__, __LINE__, \
michael@0:         enable)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful for debugging. */
michael@0: 
michael@0:   /* Request to trace every access to "address". */
michael@0:   #define ANNOTATE_TRACE_MEMORY(address) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateTraceMemory)(__FILE__, __LINE__, address)
michael@0: 
michael@0:   /* Report the current thread name to a race detector. */
michael@0:   #define ANNOTATE_THREAD_NAME(name) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateThreadName)(__FILE__, __LINE__, name)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful when implementing locks.  They are not
michael@0:      normally needed by modules that merely use locks.
michael@0:      The "lock" argument is a pointer to the lock object. */
michael@0: 
michael@0:   /* Report that a lock has been created at address "lock". */
michael@0:   #define ANNOTATE_RWLOCK_CREATE(lock) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockCreate)(__FILE__, __LINE__, lock)
michael@0: 
michael@0:   /* Report that the lock at address "lock" is about to be destroyed. */
michael@0:   #define ANNOTATE_RWLOCK_DESTROY(lock) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockDestroy)(__FILE__, __LINE__, lock)
michael@0: 
michael@0:   /* Report that the lock at address "lock" has been acquired.
michael@0:      is_w=1 for writer lock, is_w=0 for reader lock. */
michael@0:   #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockAcquired)(__FILE__, __LINE__, lock, \
michael@0:         is_w)
michael@0: 
michael@0:   /* Report that the lock at address "lock" is about to be released. */
michael@0:   #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockReleased)(__FILE__, __LINE__, lock, \
michael@0:         is_w)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful when implementing barriers.  They are not
michael@0:      normally needed by modules that merely use barriers.
michael@0:      The "barrier" argument is a pointer to the barrier object. */
michael@0: 
michael@0:   /* Report that the "barrier" has been initialized with initial "count".
michael@0:    If 'reinitialization_allowed' is true, initialization is allowed to happen
michael@0:    multiple times w/o calling barrier_destroy() */
michael@0:   #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierInit)(__FILE__, __LINE__, barrier, \
michael@0:         count, reinitialization_allowed)
michael@0: 
michael@0:   /* Report that we are about to enter barrier_wait("barrier"). */
michael@0:   #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierWaitBefore)(__FILE__, __LINE__, \
michael@0:         barrier)
michael@0: 
michael@0:   /* Report that we just exited barrier_wait("barrier"). */
michael@0:   #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierWaitAfter)(__FILE__, __LINE__, \
michael@0:         barrier)
michael@0: 
michael@0:   /* Report that the "barrier" has been destroyed. */
michael@0:   #define ANNOTATE_BARRIER_DESTROY(barrier) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierDestroy)(__FILE__, __LINE__, \
michael@0:         barrier)
michael@0: 
michael@0:   /* -------------------------------------------------------------
michael@0:      Annotations useful for testing race detectors. */
michael@0: 
michael@0:   /* Report that we expect a race on the variable at "address".
michael@0:      Use only in unit tests for a race detector. */
michael@0:   #define ANNOTATE_EXPECT_RACE(address, description) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateExpectRace)(__FILE__, __LINE__, address, \
michael@0:         description)
michael@0: 
michael@0:   #define ANNOTATE_FLUSH_EXPECTED_RACES() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateFlushExpectedRaces)(__FILE__, __LINE__)
michael@0: 
michael@0:   /* A no-op. Insert where you like to test the interceptors. */
michael@0:   #define ANNOTATE_NO_OP(arg) \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateNoOp)(__FILE__, __LINE__, arg)
michael@0: 
michael@0:   /* Force the race detector to flush its state. The actual effect depends on
michael@0:    * the implementation of the detector. */
michael@0:   #define ANNOTATE_FLUSH_STATE() \
michael@0:     DYNAMIC_ANNOTATIONS_NAME(AnnotateFlushState)(__FILE__, __LINE__)
michael@0: 
michael@0: 
michael@0: #else  /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
michael@0: 
michael@0:   #define ANNOTATE_RWLOCK_CREATE(lock) /* empty */
michael@0:   #define ANNOTATE_RWLOCK_DESTROY(lock) /* empty */
michael@0:   #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) /* empty */
michael@0:   #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) /* empty */
michael@0:   #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) /* */
michael@0:   #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) /* empty */
michael@0:   #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) /* empty */
michael@0:   #define ANNOTATE_BARRIER_DESTROY(barrier) /* empty */
michael@0:   #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) /* empty */
michael@0:   #define ANNOTATE_CONDVAR_WAIT(cv) /* empty */
michael@0:   #define ANNOTATE_CONDVAR_SIGNAL(cv) /* empty */
michael@0:   #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) /* empty */
michael@0:   #define ANNOTATE_HAPPENS_BEFORE(obj) /* empty */
michael@0:   #define ANNOTATE_HAPPENS_AFTER(obj) /* empty */
michael@0:   #define ANNOTATE_PUBLISH_MEMORY_RANGE(address, size) /* empty */
michael@0:   #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(address, size)  /* empty */
michael@0:   #define ANNOTATE_SWAP_MEMORY_RANGE(address, size)  /* empty */
michael@0:   #define ANNOTATE_PCQ_CREATE(pcq) /* empty */
michael@0:   #define ANNOTATE_PCQ_DESTROY(pcq) /* empty */
michael@0:   #define ANNOTATE_PCQ_PUT(pcq) /* empty */
michael@0:   #define ANNOTATE_PCQ_GET(pcq) /* empty */
michael@0:   #define ANNOTATE_NEW_MEMORY(address, size) /* empty */
michael@0:   #define ANNOTATE_EXPECT_RACE(address, description) /* empty */
michael@0:   #define ANNOTATE_FLUSH_EXPECTED_RACES(address, description) /* empty */
michael@0:   #define ANNOTATE_BENIGN_RACE(address, description) /* empty */
michael@0:   #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) /* empty */
michael@0:   #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) /* empty */
michael@0:   #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) /* empty */
michael@0:   #define ANNOTATE_TRACE_MEMORY(arg) /* empty */
michael@0:   #define ANNOTATE_THREAD_NAME(name) /* empty */
michael@0:   #define ANNOTATE_IGNORE_READS_BEGIN() /* empty */
michael@0:   #define ANNOTATE_IGNORE_READS_END() /* empty */
michael@0:   #define ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */
michael@0:   #define ANNOTATE_IGNORE_WRITES_END() /* empty */
michael@0:   #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */
michael@0:   #define ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */
michael@0:   #define ANNOTATE_IGNORE_SYNC_BEGIN() /* empty */
michael@0:   #define ANNOTATE_IGNORE_SYNC_END() /* empty */
michael@0:   #define ANNOTATE_ENABLE_RACE_DETECTION(enable) /* empty */
michael@0:   #define ANNOTATE_NO_OP(arg) /* empty */
michael@0:   #define ANNOTATE_FLUSH_STATE() /* empty */
michael@0: 
michael@0: #endif  /* DYNAMIC_ANNOTATIONS_ENABLED */
michael@0: 
michael@0: /* Use the macros above rather than using these functions directly. */
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: 
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockCreate)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *lock) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockDestroy)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *lock) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockAcquired)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *lock, long is_w) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateRWLockReleased)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *lock, long is_w) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierInit)(
michael@0:     const char *file, int line, const volatile void *barrier, long count,
michael@0:     long reinitialization_allowed) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierWaitBefore)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *barrier) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierWaitAfter)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *barrier) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBarrierDestroy)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *barrier) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarWait)(
michael@0:     const char *file, int line, const volatile void *cv,
michael@0:     const volatile void *lock) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarSignal)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *cv) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateCondVarSignalAll)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *cv) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateHappensBefore)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *obj) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateHappensAfter)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *obj) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotatePublishMemoryRange)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *address, long size) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateUnpublishMemoryRange)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *address, long size) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQCreate)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *pcq) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQDestroy)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *pcq) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQPut)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *pcq) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotatePCQGet)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *pcq) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateNewMemory)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *mem, long size) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateExpectRace)(
michael@0:     const char *file, int line, const volatile void *mem,
michael@0:     const char *description) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateFlushExpectedRaces)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBenignRace)(
michael@0:     const char *file, int line, const volatile void *mem,
michael@0:     const char *description) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateBenignRaceSized)(
michael@0:     const char *file, int line, const volatile void *mem, long size,
michael@0:     const char *description) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateMutexIsUsedAsCondVar)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *mu) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateMutexIsNotPHB)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *mu) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateTraceMemory)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *arg) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateThreadName)(
michael@0:     const char *file, int line,
michael@0:     const char *name) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreReadsBegin)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreReadsEnd)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreWritesBegin)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreWritesEnd)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreSyncBegin)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateIgnoreSyncEnd)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateEnableRaceDetection)(
michael@0:     const char *file, int line, int enable) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateNoOp)(
michael@0:     const char *file, int line,
michael@0:     const volatile void *arg) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: void DYNAMIC_ANNOTATIONS_NAME(AnnotateFlushState)(
michael@0:     const char *file, int line) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: 
michael@0: #if DYNAMIC_ANNOTATIONS_PROVIDE_RUNNING_ON_VALGRIND == 1
michael@0: /* Return non-zero value if running under valgrind.
michael@0: 
michael@0:   If "valgrind.h" is included into dynamic_annotations.c,
michael@0:   the regular valgrind mechanism will be used.
michael@0:   See http://valgrind.org/docs/manual/manual-core-adv.html about
michael@0:   RUNNING_ON_VALGRIND and other valgrind "client requests".
michael@0:   The file "valgrind.h" may be obtained by doing
michael@0:      svn co svn://svn.valgrind.org/valgrind/trunk/include
michael@0: 
michael@0:   If for some reason you can't use "valgrind.h" or want to fake valgrind,
michael@0:   there are two ways to make this function return non-zero:
michael@0:     - Use environment variable: export RUNNING_ON_VALGRIND=1
michael@0:     - Make your tool intercept the function RunningOnValgrind() and
michael@0:       change its return value.
michael@0:  */
michael@0: int RunningOnValgrind(void) DYNAMIC_ANNOTATIONS_ATTRIBUTE_WEAK;
michael@0: #endif /* DYNAMIC_ANNOTATIONS_PROVIDE_RUNNING_ON_VALGRIND == 1 */
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #if DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus)
michael@0: 
michael@0:   /* ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads.
michael@0: 
michael@0:      Instead of doing
michael@0:         ANNOTATE_IGNORE_READS_BEGIN();
michael@0:         ... = x;
michael@0:         ANNOTATE_IGNORE_READS_END();
michael@0:      one can use
michael@0:         ... = ANNOTATE_UNPROTECTED_READ(x); */
michael@0:   template <class T>
michael@0:   inline T ANNOTATE_UNPROTECTED_READ(const volatile T &x) {
michael@0:     ANNOTATE_IGNORE_READS_BEGIN();
michael@0:     T res = x;
michael@0:     ANNOTATE_IGNORE_READS_END();
michael@0:     return res;
michael@0:   }
michael@0:   /* Apply ANNOTATE_BENIGN_RACE_SIZED to a static variable. */
michael@0:   #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description)        \
michael@0:     namespace {                                                       \
michael@0:       class static_var ## _annotator {                                \
michael@0:        public:                                                        \
michael@0:         static_var ## _annotator() {                                  \
michael@0:           ANNOTATE_BENIGN_RACE_SIZED(&static_var,                     \
michael@0:                                       sizeof(static_var),             \
michael@0:             # static_var ": " description);                           \
michael@0:         }                                                             \
michael@0:       };                                                              \
michael@0:       static static_var ## _annotator the ## static_var ## _annotator;\
michael@0:     }
michael@0: #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
michael@0: 
michael@0:   #define ANNOTATE_UNPROTECTED_READ(x) (x)
michael@0:   #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description)  /* empty */
michael@0: 
michael@0: #endif /* DYNAMIC_ANNOTATIONS_ENABLED */
michael@0: 
michael@0: #endif  /* __DYNAMIC_ANNOTATIONS_H__ */