jpayne@69: /* Copyright (c) 2008-2009, Google Inc. jpayne@69: * All rights reserved. jpayne@69: * jpayne@69: * Redistribution and use in source and binary forms, with or without jpayne@69: * modification, are permitted provided that the following conditions are jpayne@69: * met: jpayne@69: * jpayne@69: * * Redistributions of source code must retain the above copyright jpayne@69: * notice, this list of conditions and the following disclaimer. jpayne@69: * * Neither the name of Google Inc. nor the names of its jpayne@69: * contributors may be used to endorse or promote products derived from jpayne@69: * this software without specific prior written permission. jpayne@69: * jpayne@69: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS jpayne@69: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT jpayne@69: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR jpayne@69: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT jpayne@69: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, jpayne@69: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT jpayne@69: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, jpayne@69: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY jpayne@69: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT jpayne@69: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE jpayne@69: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. jpayne@69: * jpayne@69: * --- jpayne@69: * Author: Kostya Serebryany jpayne@69: * Copied to CPython by Jeffrey Yasskin, with all macros renamed to jpayne@69: * start with _Py_ to avoid colliding with users embedding Python, and jpayne@69: * with deprecated macros removed. jpayne@69: */ jpayne@69: jpayne@69: /* This file defines dynamic annotations for use with dynamic analysis jpayne@69: tool such as valgrind, PIN, etc. jpayne@69: jpayne@69: Dynamic annotation is a source code annotation that affects jpayne@69: the generated code (that is, the annotation is not a comment). jpayne@69: Each such annotation is attached to a particular jpayne@69: instruction and/or to a particular object (address) in the program. jpayne@69: jpayne@69: The annotations that should be used by users are macros in all upper-case jpayne@69: (e.g., _Py_ANNOTATE_NEW_MEMORY). jpayne@69: jpayne@69: Actual implementation of these macros may differ depending on the jpayne@69: dynamic analysis tool being used. jpayne@69: jpayne@69: See http://code.google.com/p/data-race-test/ for more information. jpayne@69: jpayne@69: This file supports the following dynamic analysis tools: jpayne@69: - None (DYNAMIC_ANNOTATIONS_ENABLED is not defined or zero). jpayne@69: Macros are defined empty. jpayne@69: - ThreadSanitizer, Helgrind, DRD (DYNAMIC_ANNOTATIONS_ENABLED is 1). jpayne@69: Macros are defined as calls to non-inlinable empty functions jpayne@69: that are intercepted by Valgrind. */ jpayne@69: jpayne@69: #ifndef __DYNAMIC_ANNOTATIONS_H__ jpayne@69: #define __DYNAMIC_ANNOTATIONS_H__ jpayne@69: jpayne@69: #ifndef DYNAMIC_ANNOTATIONS_ENABLED jpayne@69: # define DYNAMIC_ANNOTATIONS_ENABLED 0 jpayne@69: #endif jpayne@69: jpayne@69: #if DYNAMIC_ANNOTATIONS_ENABLED != 0 jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful when implementing condition variables such as CondVar, jpayne@69: using conditional critical sections (Await/LockWhen) and when constructing jpayne@69: user-defined synchronization mechanisms. jpayne@69: jpayne@69: The annotations _Py_ANNOTATE_HAPPENS_BEFORE() and jpayne@69: _Py_ANNOTATE_HAPPENS_AFTER() can be used to define happens-before arcs in jpayne@69: user-defined synchronization mechanisms: the race detector will infer an jpayne@69: arc from the former to the latter when they share the same argument jpayne@69: pointer. jpayne@69: jpayne@69: Example 1 (reference counting): jpayne@69: jpayne@69: void Unref() { jpayne@69: _Py_ANNOTATE_HAPPENS_BEFORE(&refcount_); jpayne@69: if (AtomicDecrementByOne(&refcount_) == 0) { jpayne@69: _Py_ANNOTATE_HAPPENS_AFTER(&refcount_); jpayne@69: delete this; jpayne@69: } jpayne@69: } jpayne@69: jpayne@69: Example 2 (message queue): jpayne@69: jpayne@69: void MyQueue::Put(Type *e) { jpayne@69: MutexLock lock(&mu_); jpayne@69: _Py_ANNOTATE_HAPPENS_BEFORE(e); jpayne@69: PutElementIntoMyQueue(e); jpayne@69: } jpayne@69: jpayne@69: Type *MyQueue::Get() { jpayne@69: MutexLock lock(&mu_); jpayne@69: Type *e = GetElementFromMyQueue(); jpayne@69: _Py_ANNOTATE_HAPPENS_AFTER(e); jpayne@69: return e; jpayne@69: } jpayne@69: jpayne@69: Note: when possible, please use the existing reference counting and message jpayne@69: queue implementations instead of inventing new ones. */ jpayne@69: jpayne@69: /* Report that wait on the condition variable at address "cv" has succeeded jpayne@69: and the lock at address "lock" is held. */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \ jpayne@69: AnnotateCondVarWait(__FILE__, __LINE__, cv, lock) jpayne@69: jpayne@69: /* Report that wait on the condition variable at "cv" has succeeded. Variant jpayne@69: w/o lock. */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_WAIT(cv) \ jpayne@69: AnnotateCondVarWait(__FILE__, __LINE__, cv, NULL) jpayne@69: jpayne@69: /* Report that we are about to signal on the condition variable at address jpayne@69: "cv". */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_SIGNAL(cv) \ jpayne@69: AnnotateCondVarSignal(__FILE__, __LINE__, cv) jpayne@69: jpayne@69: /* Report that we are about to signal_all on the condition variable at "cv". */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \ jpayne@69: AnnotateCondVarSignalAll(__FILE__, __LINE__, cv) jpayne@69: jpayne@69: /* Annotations for user-defined synchronization mechanisms. */ jpayne@69: #define _Py_ANNOTATE_HAPPENS_BEFORE(obj) _Py_ANNOTATE_CONDVAR_SIGNAL(obj) jpayne@69: #define _Py_ANNOTATE_HAPPENS_AFTER(obj) _Py_ANNOTATE_CONDVAR_WAIT(obj) jpayne@69: jpayne@69: /* Report that the bytes in the range [pointer, pointer+size) are about jpayne@69: to be published safely. The race checker will create a happens-before jpayne@69: arc from the call _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) to jpayne@69: subsequent accesses to this memory. jpayne@69: Note: this annotation may not work properly if the race detector uses jpayne@69: sampling, i.e. does not observe all memory accesses. jpayne@69: */ jpayne@69: #define _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \ jpayne@69: AnnotatePublishMemoryRange(__FILE__, __LINE__, pointer, size) jpayne@69: jpayne@69: /* Instruct the tool to create a happens-before arc between mu->Unlock() and jpayne@69: mu->Lock(). This annotation may slow down the race detector and hide real jpayne@69: races. Normally it is used only when it would be difficult to annotate each jpayne@69: of the mutex's critical sections individually using the annotations above. jpayne@69: This annotation makes sense only for hybrid race detectors. For pure jpayne@69: happens-before detectors this is a no-op. For more details see jpayne@69: http://code.google.com/p/data-race-test/wiki/PureHappensBeforeVsHybrid . */ jpayne@69: #define _Py_ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \ jpayne@69: AnnotateMutexIsUsedAsCondVar(__FILE__, __LINE__, mu) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful when defining memory allocators, or when memory that jpayne@69: was protected in one way starts to be protected in another. */ jpayne@69: jpayne@69: /* Report that a new memory at "address" of size "size" has been allocated. jpayne@69: This might be used when the memory has been retrieved from a free list and jpayne@69: is about to be reused, or when the locking discipline for a variable jpayne@69: changes. */ jpayne@69: #define _Py_ANNOTATE_NEW_MEMORY(address, size) \ jpayne@69: AnnotateNewMemory(__FILE__, __LINE__, address, size) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful when defining FIFO queues that transfer data between jpayne@69: threads. */ jpayne@69: jpayne@69: /* Report that the producer-consumer queue (such as ProducerConsumerQueue) at jpayne@69: address "pcq" has been created. The _Py_ANNOTATE_PCQ_* annotations should jpayne@69: be used only for FIFO queues. For non-FIFO queues use jpayne@69: _Py_ANNOTATE_HAPPENS_BEFORE (for put) and _Py_ANNOTATE_HAPPENS_AFTER (for jpayne@69: get). */ jpayne@69: #define _Py_ANNOTATE_PCQ_CREATE(pcq) \ jpayne@69: AnnotatePCQCreate(__FILE__, __LINE__, pcq) jpayne@69: jpayne@69: /* Report that the queue at address "pcq" is about to be destroyed. */ jpayne@69: #define _Py_ANNOTATE_PCQ_DESTROY(pcq) \ jpayne@69: AnnotatePCQDestroy(__FILE__, __LINE__, pcq) jpayne@69: jpayne@69: /* Report that we are about to put an element into a FIFO queue at address jpayne@69: "pcq". */ jpayne@69: #define _Py_ANNOTATE_PCQ_PUT(pcq) \ jpayne@69: AnnotatePCQPut(__FILE__, __LINE__, pcq) jpayne@69: jpayne@69: /* Report that we've just got an element from a FIFO queue at address "pcq". */ jpayne@69: #define _Py_ANNOTATE_PCQ_GET(pcq) \ jpayne@69: AnnotatePCQGet(__FILE__, __LINE__, pcq) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations that suppress errors. It is usually better to express the jpayne@69: program's synchronization using the other annotations, but these can jpayne@69: be used when all else fails. */ jpayne@69: jpayne@69: /* Report that we may have a benign race at "pointer", with size jpayne@69: "sizeof(*(pointer))". "pointer" must be a non-void* pointer. Insert at the jpayne@69: point where "pointer" has been allocated, preferably close to the point jpayne@69: where the race happens. See also _Py_ANNOTATE_BENIGN_RACE_STATIC. */ jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE(pointer, description) \ jpayne@69: AnnotateBenignRaceSized(__FILE__, __LINE__, pointer, \ jpayne@69: sizeof(*(pointer)), description) jpayne@69: jpayne@69: /* Same as _Py_ANNOTATE_BENIGN_RACE(address, description), but applies to jpayne@69: the memory range [address, address+size). */ jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ jpayne@69: AnnotateBenignRaceSized(__FILE__, __LINE__, address, size, description) jpayne@69: jpayne@69: /* Request the analysis tool to ignore all reads in the current thread jpayne@69: until _Py_ANNOTATE_IGNORE_READS_END is called. jpayne@69: Useful to ignore intentional racey reads, while still checking jpayne@69: other reads and all writes. jpayne@69: See also _Py_ANNOTATE_UNPROTECTED_READ. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_BEGIN() \ jpayne@69: AnnotateIgnoreReadsBegin(__FILE__, __LINE__) jpayne@69: jpayne@69: /* Stop ignoring reads. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_END() \ jpayne@69: AnnotateIgnoreReadsEnd(__FILE__, __LINE__) jpayne@69: jpayne@69: /* Similar to _Py_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_WRITES_BEGIN() \ jpayne@69: AnnotateIgnoreWritesBegin(__FILE__, __LINE__) jpayne@69: jpayne@69: /* Stop ignoring writes. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_WRITES_END() \ jpayne@69: AnnotateIgnoreWritesEnd(__FILE__, __LINE__) jpayne@69: jpayne@69: /* Start ignoring all memory accesses (reads and writes). */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ jpayne@69: do {\ jpayne@69: _Py_ANNOTATE_IGNORE_READS_BEGIN();\ jpayne@69: _Py_ANNOTATE_IGNORE_WRITES_BEGIN();\ jpayne@69: }while(0)\ jpayne@69: jpayne@69: /* Stop ignoring all memory accesses. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_END() \ jpayne@69: do {\ jpayne@69: _Py_ANNOTATE_IGNORE_WRITES_END();\ jpayne@69: _Py_ANNOTATE_IGNORE_READS_END();\ jpayne@69: }while(0)\ jpayne@69: jpayne@69: /* Similar to _Py_ANNOTATE_IGNORE_READS_BEGIN, but ignore synchronization events: jpayne@69: RWLOCK* and CONDVAR*. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_SYNC_BEGIN() \ jpayne@69: AnnotateIgnoreSyncBegin(__FILE__, __LINE__) jpayne@69: jpayne@69: /* Stop ignoring sync events. */ jpayne@69: #define _Py_ANNOTATE_IGNORE_SYNC_END() \ jpayne@69: AnnotateIgnoreSyncEnd(__FILE__, __LINE__) jpayne@69: jpayne@69: jpayne@69: /* Enable (enable!=0) or disable (enable==0) race detection for all threads. jpayne@69: This annotation could be useful if you want to skip expensive race analysis jpayne@69: during some period of program execution, e.g. during initialization. */ jpayne@69: #define _Py_ANNOTATE_ENABLE_RACE_DETECTION(enable) \ jpayne@69: AnnotateEnableRaceDetection(__FILE__, __LINE__, enable) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful for debugging. */ jpayne@69: jpayne@69: /* Request to trace every access to "address". */ jpayne@69: #define _Py_ANNOTATE_TRACE_MEMORY(address) \ jpayne@69: AnnotateTraceMemory(__FILE__, __LINE__, address) jpayne@69: jpayne@69: /* Report the current thread name to a race detector. */ jpayne@69: #define _Py_ANNOTATE_THREAD_NAME(name) \ jpayne@69: AnnotateThreadName(__FILE__, __LINE__, name) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful when implementing locks. They are not jpayne@69: normally needed by modules that merely use locks. jpayne@69: The "lock" argument is a pointer to the lock object. */ jpayne@69: jpayne@69: /* Report that a lock has been created at address "lock". */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_CREATE(lock) \ jpayne@69: AnnotateRWLockCreate(__FILE__, __LINE__, lock) jpayne@69: jpayne@69: /* Report that the lock at address "lock" is about to be destroyed. */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_DESTROY(lock) \ jpayne@69: AnnotateRWLockDestroy(__FILE__, __LINE__, lock) jpayne@69: jpayne@69: /* Report that the lock at address "lock" has been acquired. jpayne@69: is_w=1 for writer lock, is_w=0 for reader lock. */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ jpayne@69: AnnotateRWLockAcquired(__FILE__, __LINE__, lock, is_w) jpayne@69: jpayne@69: /* Report that the lock at address "lock" is about to be released. */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ jpayne@69: AnnotateRWLockReleased(__FILE__, __LINE__, lock, is_w) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful when implementing barriers. They are not jpayne@69: normally needed by modules that merely use barriers. jpayne@69: The "barrier" argument is a pointer to the barrier object. */ jpayne@69: jpayne@69: /* Report that the "barrier" has been initialized with initial "count". jpayne@69: If 'reinitialization_allowed' is true, initialization is allowed to happen jpayne@69: multiple times w/o calling barrier_destroy() */ jpayne@69: #define _Py_ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \ jpayne@69: AnnotateBarrierInit(__FILE__, __LINE__, barrier, count, \ jpayne@69: reinitialization_allowed) jpayne@69: jpayne@69: /* Report that we are about to enter barrier_wait("barrier"). */ jpayne@69: #define _Py_ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \ jpayne@69: AnnotateBarrierWaitBefore(__FILE__, __LINE__, barrier) jpayne@69: jpayne@69: /* Report that we just exited barrier_wait("barrier"). */ jpayne@69: #define _Py_ANNOTATE_BARRIER_WAIT_AFTER(barrier) \ jpayne@69: AnnotateBarrierWaitAfter(__FILE__, __LINE__, barrier) jpayne@69: jpayne@69: /* Report that the "barrier" has been destroyed. */ jpayne@69: #define _Py_ANNOTATE_BARRIER_DESTROY(barrier) \ jpayne@69: AnnotateBarrierDestroy(__FILE__, __LINE__, barrier) jpayne@69: jpayne@69: /* ------------------------------------------------------------- jpayne@69: Annotations useful for testing race detectors. */ jpayne@69: jpayne@69: /* Report that we expect a race on the variable at "address". jpayne@69: Use only in unit tests for a race detector. */ jpayne@69: #define _Py_ANNOTATE_EXPECT_RACE(address, description) \ jpayne@69: AnnotateExpectRace(__FILE__, __LINE__, address, description) jpayne@69: jpayne@69: /* A no-op. Insert where you like to test the interceptors. */ jpayne@69: #define _Py_ANNOTATE_NO_OP(arg) \ jpayne@69: AnnotateNoOp(__FILE__, __LINE__, arg) jpayne@69: jpayne@69: /* Force the race detector to flush its state. The actual effect depends on jpayne@69: * the implementation of the detector. */ jpayne@69: #define _Py_ANNOTATE_FLUSH_STATE() \ jpayne@69: AnnotateFlushState(__FILE__, __LINE__) jpayne@69: jpayne@69: jpayne@69: #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */ jpayne@69: jpayne@69: #define _Py_ANNOTATE_RWLOCK_CREATE(lock) /* empty */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_DESTROY(lock) /* empty */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) /* empty */ jpayne@69: #define _Py_ANNOTATE_RWLOCK_RELEASED(lock, is_w) /* empty */ jpayne@69: #define _Py_ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) /* */ jpayne@69: #define _Py_ANNOTATE_BARRIER_WAIT_BEFORE(barrier) /* empty */ jpayne@69: #define _Py_ANNOTATE_BARRIER_WAIT_AFTER(barrier) /* empty */ jpayne@69: #define _Py_ANNOTATE_BARRIER_DESTROY(barrier) /* empty */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) /* empty */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_WAIT(cv) /* empty */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_SIGNAL(cv) /* empty */ jpayne@69: #define _Py_ANNOTATE_CONDVAR_SIGNAL_ALL(cv) /* empty */ jpayne@69: #define _Py_ANNOTATE_HAPPENS_BEFORE(obj) /* empty */ jpayne@69: #define _Py_ANNOTATE_HAPPENS_AFTER(obj) /* empty */ jpayne@69: #define _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(address, size) /* empty */ jpayne@69: #define _Py_ANNOTATE_UNPUBLISH_MEMORY_RANGE(address, size) /* empty */ jpayne@69: #define _Py_ANNOTATE_SWAP_MEMORY_RANGE(address, size) /* empty */ jpayne@69: #define _Py_ANNOTATE_PCQ_CREATE(pcq) /* empty */ jpayne@69: #define _Py_ANNOTATE_PCQ_DESTROY(pcq) /* empty */ jpayne@69: #define _Py_ANNOTATE_PCQ_PUT(pcq) /* empty */ jpayne@69: #define _Py_ANNOTATE_PCQ_GET(pcq) /* empty */ jpayne@69: #define _Py_ANNOTATE_NEW_MEMORY(address, size) /* empty */ jpayne@69: #define _Py_ANNOTATE_EXPECT_RACE(address, description) /* empty */ jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE(address, description) /* empty */ jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) /* empty */ jpayne@69: #define _Py_ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) /* empty */ jpayne@69: #define _Py_ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) /* empty */ jpayne@69: #define _Py_ANNOTATE_TRACE_MEMORY(arg) /* empty */ jpayne@69: #define _Py_ANNOTATE_THREAD_NAME(name) /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_BEGIN() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_END() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_WRITES_END() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_SYNC_BEGIN() /* empty */ jpayne@69: #define _Py_ANNOTATE_IGNORE_SYNC_END() /* empty */ jpayne@69: #define _Py_ANNOTATE_ENABLE_RACE_DETECTION(enable) /* empty */ jpayne@69: #define _Py_ANNOTATE_NO_OP(arg) /* empty */ jpayne@69: #define _Py_ANNOTATE_FLUSH_STATE() /* empty */ jpayne@69: jpayne@69: #endif /* DYNAMIC_ANNOTATIONS_ENABLED */ jpayne@69: jpayne@69: /* Use the macros above rather than using these functions directly. */ jpayne@69: #ifdef __cplusplus jpayne@69: extern "C" { jpayne@69: #endif jpayne@69: void AnnotateRWLockCreate(const char *file, int line, jpayne@69: const volatile void *lock); jpayne@69: void AnnotateRWLockDestroy(const char *file, int line, jpayne@69: const volatile void *lock); jpayne@69: void AnnotateRWLockAcquired(const char *file, int line, jpayne@69: const volatile void *lock, long is_w); jpayne@69: void AnnotateRWLockReleased(const char *file, int line, jpayne@69: const volatile void *lock, long is_w); jpayne@69: void AnnotateBarrierInit(const char *file, int line, jpayne@69: const volatile void *barrier, long count, jpayne@69: long reinitialization_allowed); jpayne@69: void AnnotateBarrierWaitBefore(const char *file, int line, jpayne@69: const volatile void *barrier); jpayne@69: void AnnotateBarrierWaitAfter(const char *file, int line, jpayne@69: const volatile void *barrier); jpayne@69: void AnnotateBarrierDestroy(const char *file, int line, jpayne@69: const volatile void *barrier); jpayne@69: void AnnotateCondVarWait(const char *file, int line, jpayne@69: const volatile void *cv, jpayne@69: const volatile void *lock); jpayne@69: void AnnotateCondVarSignal(const char *file, int line, jpayne@69: const volatile void *cv); jpayne@69: void AnnotateCondVarSignalAll(const char *file, int line, jpayne@69: const volatile void *cv); jpayne@69: void AnnotatePublishMemoryRange(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: long size); jpayne@69: void AnnotateUnpublishMemoryRange(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: long size); jpayne@69: void AnnotatePCQCreate(const char *file, int line, jpayne@69: const volatile void *pcq); jpayne@69: void AnnotatePCQDestroy(const char *file, int line, jpayne@69: const volatile void *pcq); jpayne@69: void AnnotatePCQPut(const char *file, int line, jpayne@69: const volatile void *pcq); jpayne@69: void AnnotatePCQGet(const char *file, int line, jpayne@69: const volatile void *pcq); jpayne@69: void AnnotateNewMemory(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: long size); jpayne@69: void AnnotateExpectRace(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: const char *description); jpayne@69: void AnnotateBenignRace(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: const char *description); jpayne@69: void AnnotateBenignRaceSized(const char *file, int line, jpayne@69: const volatile void *address, jpayne@69: long size, jpayne@69: const char *description); jpayne@69: void AnnotateMutexIsUsedAsCondVar(const char *file, int line, jpayne@69: const volatile void *mu); jpayne@69: void AnnotateTraceMemory(const char *file, int line, jpayne@69: const volatile void *arg); jpayne@69: void AnnotateThreadName(const char *file, int line, jpayne@69: const char *name); jpayne@69: void AnnotateIgnoreReadsBegin(const char *file, int line); jpayne@69: void AnnotateIgnoreReadsEnd(const char *file, int line); jpayne@69: void AnnotateIgnoreWritesBegin(const char *file, int line); jpayne@69: void AnnotateIgnoreWritesEnd(const char *file, int line); jpayne@69: void AnnotateEnableRaceDetection(const char *file, int line, int enable); jpayne@69: void AnnotateNoOp(const char *file, int line, jpayne@69: const volatile void *arg); jpayne@69: void AnnotateFlushState(const char *file, int line); jpayne@69: jpayne@69: /* Return non-zero value if running under valgrind. jpayne@69: jpayne@69: If "valgrind.h" is included into dynamic_annotations.c, jpayne@69: the regular valgrind mechanism will be used. jpayne@69: See http://valgrind.org/docs/manual/manual-core-adv.html about jpayne@69: RUNNING_ON_VALGRIND and other valgrind "client requests". jpayne@69: The file "valgrind.h" may be obtained by doing jpayne@69: svn co svn://svn.valgrind.org/valgrind/trunk/include jpayne@69: jpayne@69: If for some reason you can't use "valgrind.h" or want to fake valgrind, jpayne@69: there are two ways to make this function return non-zero: jpayne@69: - Use environment variable: export RUNNING_ON_VALGRIND=1 jpayne@69: - Make your tool intercept the function RunningOnValgrind() and jpayne@69: change its return value. jpayne@69: */ jpayne@69: int RunningOnValgrind(void); jpayne@69: jpayne@69: #ifdef __cplusplus jpayne@69: } jpayne@69: #endif jpayne@69: jpayne@69: #if DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus) jpayne@69: jpayne@69: /* _Py_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads. jpayne@69: jpayne@69: Instead of doing jpayne@69: _Py_ANNOTATE_IGNORE_READS_BEGIN(); jpayne@69: ... = x; jpayne@69: _Py_ANNOTATE_IGNORE_READS_END(); jpayne@69: one can use jpayne@69: ... = _Py_ANNOTATE_UNPROTECTED_READ(x); */ jpayne@69: template jpayne@69: inline T _Py_ANNOTATE_UNPROTECTED_READ(const volatile T &x) { jpayne@69: _Py_ANNOTATE_IGNORE_READS_BEGIN(); jpayne@69: T res = x; jpayne@69: _Py_ANNOTATE_IGNORE_READS_END(); jpayne@69: return res; jpayne@69: } jpayne@69: /* Apply _Py_ANNOTATE_BENIGN_RACE_SIZED to a static variable. */ jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \ jpayne@69: namespace { \ jpayne@69: class static_var ## _annotator { \ jpayne@69: public: \ jpayne@69: static_var ## _annotator() { \ jpayne@69: _Py_ANNOTATE_BENIGN_RACE_SIZED(&static_var, \ jpayne@69: sizeof(static_var), \ jpayne@69: # static_var ": " description); \ jpayne@69: } \ jpayne@69: }; \ jpayne@69: static static_var ## _annotator the ## static_var ## _annotator;\ jpayne@69: } jpayne@69: #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */ jpayne@69: jpayne@69: #define _Py_ANNOTATE_UNPROTECTED_READ(x) (x) jpayne@69: #define _Py_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) /* empty */ jpayne@69: jpayne@69: #endif /* DYNAMIC_ANNOTATIONS_ENABLED */ jpayne@69: jpayne@69: #endif /* __DYNAMIC_ANNOTATIONS_H__ */