include/python3.12/dynamic_annotations.h

0001 /* Copyright (c) 2008-2009, Google Inc.
0002  * All rights reserved.
0003  *
0004  * Redistribution and use in source and binary forms, with or without
0005  * modification, are permitted provided that the following conditions are
0006  * met:
0007  *
0008  *     * Redistributions of source code must retain the above copyright
0009  * notice, this list of conditions and the following disclaimer.
0010  *     * Neither the name of Google Inc. nor the names of its
0011  * contributors may be used to endorse or promote products derived from
0012  * this software without specific prior written permission.
0013  *
0014  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
0015  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
0016  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
0017  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
0018  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
0019  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
0020  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
0021  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
0022  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0023  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
0024  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0025  *
0026  * ---
0027  * Author: Kostya Serebryany
0028  * Copied to CPython by Jeffrey Yasskin, with all macros renamed to
0029  * start with _Py_ to avoid colliding with users embedding Python, and
0030  * with deprecated macros removed.
0031  */
0032
0033 /* This file defines dynamic annotations for use with dynamic analysis
0034    tool such as valgrind, PIN, etc.
0035
0036    Dynamic annotation is a source code annotation that affects
0037    the generated code (that is, the annotation is not a comment).
0038    Each such annotation is attached to a particular
0039    instruction and/or to a particular object (address) in the program.
0040
0041    The annotations that should be used by users are macros in all upper-case
0042    (e.g., _Py_ANNOTATE_NEW_MEMORY).
0043
0044    Actual implementation of these macros may differ depending on the
0045    dynamic analysis tool being used.
0046
0047    See https://code.google.com/p/data-race-test/  for more information.
0048
0049    This file supports the following dynamic analysis tools:
0050    - None (DYNAMIC_ANNOTATIONS_ENABLED is not defined or zero).
0051       Macros are defined empty.
0052    - ThreadSanitizer, Helgrind, DRD (DYNAMIC_ANNOTATIONS_ENABLED is 1).
0053       Macros are defined as calls to non-inlinable empty functions
0054       that are intercepted by Valgrind. */
0055
0056 #ifndef __DYNAMIC_ANNOTATIONS_H__
0057 #define __DYNAMIC_ANNOTATIONS_H__
0058
0059 #ifndef DYNAMIC_ANNOTATIONS_ENABLED
0060 # define DYNAMIC_ANNOTATIONS_ENABLED 0
0061 #endif
0062
0063 #if DYNAMIC_ANNOTATIONS_ENABLED != 0
0064
0065   /* -------------------------------------------------------------
0066      Annotations useful when implementing condition variables such as CondVar,
0067      using conditional critical sections (Await/LockWhen) and when constructing
0068      user-defined synchronization mechanisms.
0069
0070      The annotations _Py_ANNOTATE_HAPPENS_BEFORE() and
0071      _Py_ANNOTATE_HAPPENS_AFTER() can be used to define happens-before arcs in
0072      user-defined synchronization mechanisms: the race detector will infer an
0073      arc from the former to the latter when they share the same argument
0074      pointer.
0075
0076      Example 1 (reference counting):
0077
0078      void Unref() {
0079        _Py_ANNOTATE_HAPPENS_BEFORE(&refcount_);
0080        if (AtomicDecrementByOne(&refcount_) == 0) {
0081          _Py_ANNOTATE_HAPPENS_AFTER(&refcount_);
0082          delete this;
0083        }
0084      }
0085
0086      Example 2 (message queue):
0087
0088      void MyQueue::Put(Type *e) {
0089        MutexLock lock(&mu_);
0090        _Py_ANNOTATE_HAPPENS_BEFORE(e);
0091        PutElementIntoMyQueue(e);
0092      }
0093
0094      Type *MyQueue::Get() {
0095        MutexLock lock(&mu_);
0096        Type *e = GetElementFromMyQueue();
0097        _Py_ANNOTATE_HAPPENS_AFTER(e);
0098        return e;
0099      }
0100
0101      Note: when possible, please use the existing reference counting and message
0102      queue implementations instead of inventing new ones. */
0103
0104   /* Report that wait on the condition variable at address "cv" has succeeded
0105      and the lock at address "lock" is held. */
0106 #define _Py_ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \
0107     AnnotateCondVarWait(__FILE__, __LINE__, cv, lock)
0108
0109   /* Report that wait on the condition variable at "cv" has succeeded.  Variant
0110      w/o lock. */
0111 #define _Py_ANNOTATE_CONDVAR_WAIT(cv) \
0112     AnnotateCondVarWait(__FILE__, __LINE__, cv, NULL)
0113
0114   /* Report that we are about to signal on the condition variable at address
0115      "cv". */
0116 #define _Py_ANNOTATE_CONDVAR_SIGNAL(cv) \
0117     AnnotateCondVarSignal(__FILE__, __LINE__, cv)
0118
0119   /* Report that we are about to signal_all on the condition variable at "cv". */
0120 #define _Py_ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \
0121     AnnotateCondVarSignalAll(__FILE__, __LINE__, cv)
0122
0123   /* Annotations for user-defined synchronization mechanisms. */
0124 #define _Py_ANNOTATE_HAPPENS_BEFORE(obj) _Py_ANNOTATE_CONDVAR_SIGNAL(obj)
0125 #define _Py_ANNOTATE_HAPPENS_AFTER(obj)  _Py_ANNOTATE_CONDVAR_WAIT(obj)
0126
0127   /* Report that the bytes in the range [pointer, pointer+size) are about
0128      to be published safely. The race checker will create a happens-before
0129      arc from the call _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) to
0130      subsequent accesses to this memory.
0131      Note: this annotation may not work properly if the race detector uses
0132      sampling, i.e. does not observe all memory accesses.
0133      */
0134 #define _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \
0135     AnnotatePublishMemoryRange(__FILE__, __LINE__, pointer, size)
0136
0137   /* Instruct the tool to create a happens-before arc between mu->Unlock() and
0138      mu->Lock(). This annotation may slow down the race detector and hide real
0139      races. Normally it is used only when it would be difficult to annotate each
0140      of the mutex's critical sections individually using the annotations above.
0141      This annotation makes sense only for hybrid race detectors. For pure
0142      happens-before detectors this is a no-op. For more details see
0143      https://code.google.com/p/data-race-test/wiki/PureHappensBeforeVsHybrid . */
0144 #define _Py_ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \
0145     AnnotateMutexIsUsedAsCondVar(__FILE__, __LINE__, mu)
0146
0147   /* -------------------------------------------------------------
0148      Annotations useful when defining memory allocators, or when memory that
0149      was protected in one way starts to be protected in another. */
0150
0151   /* Report that a new memory at "address" of size "size" has been allocated.
0152      This might be used when the memory has been retrieved from a free list and
0153      is about to be reused, or when the locking discipline for a variable
0154      changes. */
0155 #define _Py_ANNOTATE_NEW_MEMORY(address, size) \
0156     AnnotateNewMemory(__FILE__, __LINE__, address, size)
0157
0158   /* -------------------------------------------------------------
0159      Annotations useful when defining FIFO queues that transfer data between
0160      threads. */
0161
0162   /* Report that the producer-consumer queue (such as ProducerConsumerQueue) at
0163      address "pcq" has been created.  The _Py_ANNOTATE_PCQ_* annotations should
0164      be used only for FIFO queues.  For non-FIFO queues use
0165      _Py_ANNOTATE_HAPPENS_BEFORE (for put) and _Py_ANNOTATE_HAPPENS_AFTER (for
0166      get). */
0167 #define _Py_ANNOTATE_PCQ_CREATE(pcq) \
0168     AnnotatePCQCreate(__FILE__, __LINE__, pcq)
0169
0170   /* Report that the queue at address "pcq" is about to be destroyed. */
0171 #define _Py_ANNOTATE_PCQ_DESTROY(pcq) \
0172     AnnotatePCQDestroy(__FILE__, __LINE__, pcq)
0173
0174   /* Report that we are about to put an element into a FIFO queue at address
0175      "pcq". */
0176 #define _Py_ANNOTATE_PCQ_PUT(pcq) \
0177     AnnotatePCQPut(__FILE__, __LINE__, pcq)
0178
0179   /* Report that we've just got an element from a FIFO queue at address "pcq". */
0180 #define _Py_ANNOTATE_PCQ_GET(pcq) \
0181     AnnotatePCQGet(__FILE__, __LINE__, pcq)
0182
0183   /* -------------------------------------------------------------
0184      Annotations that suppress errors.  It is usually better to express the
0185      program's synchronization using the other annotations, but these can
0186      be used when all else fails. */
0187
0188   /* Report that we may have a benign race at "pointer", with size
0189      "sizeof(*(pointer))". "pointer" must be a non-void* pointer.  Insert at the
0190      point where "pointer" has been allocated, preferably close to the point
0191      where the race happens.  See also _Py_ANNOTATE_BENIGN_RACE_STATIC. */
0192 #define _Py_ANNOTATE_BENIGN_RACE(pointer, description) \
0193     AnnotateBenignRaceSized(__FILE__, __LINE__, pointer, \
0194                             sizeof(*(pointer)), description)
0195
0196   /* Same as _Py_ANNOTATE_BENIGN_RACE(address, description), but applies to
0197      the memory range [address, address+size). */
0198 #define _Py_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \
0199     AnnotateBenignRaceSized(__FILE__, __LINE__, address, size, description)
0200
0201   /* Request the analysis tool to ignore all reads in the current thread
0202      until _Py_ANNOTATE_IGNORE_READS_END is called.
0203      Useful to ignore intentional racey reads, while still checking
0204      other reads and all writes.
0205      See also _Py_ANNOTATE_UNPROTECTED_READ. */
0206 #define _Py_ANNOTATE_IGNORE_READS_BEGIN() \
0207     AnnotateIgnoreReadsBegin(__FILE__, __LINE__)
0208
0209   /* Stop ignoring reads. */
0210 #define _Py_ANNOTATE_IGNORE_READS_END() \
0211     AnnotateIgnoreReadsEnd(__FILE__, __LINE__)
0212
0213   /* Similar to _Py_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */
0214 #define _Py_ANNOTATE_IGNORE_WRITES_BEGIN() \
0215     AnnotateIgnoreWritesBegin(__FILE__, __LINE__)
0216
0217   /* Stop ignoring writes. */
0218 #define _Py_ANNOTATE_IGNORE_WRITES_END() \
0219     AnnotateIgnoreWritesEnd(__FILE__, __LINE__)
0220
0221   /* Start ignoring all memory accesses (reads and writes). */
0222 #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
0223     do {\
0224       _Py_ANNOTATE_IGNORE_READS_BEGIN();\
0225       _Py_ANNOTATE_IGNORE_WRITES_BEGIN();\
0226     }while(0)\
0227
0228   /* Stop ignoring all memory accesses. */
0229 #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_END() \
0230     do {\
0231       _Py_ANNOTATE_IGNORE_WRITES_END();\
0232       _Py_ANNOTATE_IGNORE_READS_END();\
0233     }while(0)\
0234
0235   /* Similar to _Py_ANNOTATE_IGNORE_READS_BEGIN, but ignore synchronization events:
0236      RWLOCK* and CONDVAR*. */
0237 #define _Py_ANNOTATE_IGNORE_SYNC_BEGIN() \
0238     AnnotateIgnoreSyncBegin(__FILE__, __LINE__)
0239
0240   /* Stop ignoring sync events. */
0241 #define _Py_ANNOTATE_IGNORE_SYNC_END() \
0242     AnnotateIgnoreSyncEnd(__FILE__, __LINE__)
0243
0244
0245   /* Enable (enable!=0) or disable (enable==0) race detection for all threads.
0246      This annotation could be useful if you want to skip expensive race analysis
0247      during some period of program execution, e.g. during initialization. */
0248 #define _Py_ANNOTATE_ENABLE_RACE_DETECTION(enable) \
0249     AnnotateEnableRaceDetection(__FILE__, __LINE__, enable)
0250
0251   /* -------------------------------------------------------------
0252      Annotations useful for debugging. */
0253
0254   /* Request to trace every access to "address". */
0255 #define _Py_ANNOTATE_TRACE_MEMORY(address) \
0256     AnnotateTraceMemory(__FILE__, __LINE__, address)
0257
0258   /* Report the current thread name to a race detector. */
0259 #define _Py_ANNOTATE_THREAD_NAME(name) \
0260     AnnotateThreadName(__FILE__, __LINE__, name)
0261
0262   /* -------------------------------------------------------------
0263      Annotations useful when implementing locks.  They are not
0264      normally needed by modules that merely use locks.
0265      The "lock" argument is a pointer to the lock object. */
0266
0267   /* Report that a lock has been created at address "lock". */
0268 #define _Py_ANNOTATE_RWLOCK_CREATE(lock) \
0269     AnnotateRWLockCreate(__FILE__, __LINE__, lock)
0270
0271   /* Report that the lock at address "lock" is about to be destroyed. */
0272 #define _Py_ANNOTATE_RWLOCK_DESTROY(lock) \
0273     AnnotateRWLockDestroy(__FILE__, __LINE__, lock)
0274
0275   /* Report that the lock at address "lock" has been acquired.
0276      is_w=1 for writer lock, is_w=0 for reader lock. */
0277 #define _Py_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \
0278     AnnotateRWLockAcquired(__FILE__, __LINE__, lock, is_w)
0279
0280   /* Report that the lock at address "lock" is about to be released. */
0281 #define _Py_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \
0282     AnnotateRWLockReleased(__FILE__, __LINE__, lock, is_w)
0283
0284   /* -------------------------------------------------------------
0285      Annotations useful when implementing barriers.  They are not
0286      normally needed by modules that merely use barriers.
0287      The "barrier" argument is a pointer to the barrier object. */
0288
0289   /* Report that the "barrier" has been initialized with initial "count".
0290    If 'reinitialization_allowed' is true, initialization is allowed to happen
0291    multiple times w/o calling barrier_destroy() */
0292 #define _Py_ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \
0293     AnnotateBarrierInit(__FILE__, __LINE__, barrier, count, \
0294                         reinitialization_allowed)
0295
0296   /* Report that we are about to enter barrier_wait("barrier"). */
0297 #define _Py_ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \
0298     AnnotateBarrierWaitBefore(__FILE__, __LINE__, barrier)
0299
0300   /* Report that we just exited barrier_wait("barrier"). */
0301 #define _Py_ANNOTATE_BARRIER_WAIT_AFTER(barrier) \
0302     AnnotateBarrierWaitAfter(__FILE__, __LINE__, barrier)
0303
0304   /* Report that the "barrier" has been destroyed. */
0305 #define _Py_ANNOTATE_BARRIER_DESTROY(barrier) \
0306     AnnotateBarrierDestroy(__FILE__, __LINE__, barrier)
0307
0308   /* -------------------------------------------------------------
0309      Annotations useful for testing race detectors. */
0310
0311   /* Report that we expect a race on the variable at "address".
0312      Use only in unit tests for a race detector. */
0313 #define _Py_ANNOTATE_EXPECT_RACE(address, description) \
0314     AnnotateExpectRace(__FILE__, __LINE__, address, description)
0315
0316   /* A no-op. Insert where you like to test the interceptors. */
0317 #define _Py_ANNOTATE_NO_OP(arg) \
0318     AnnotateNoOp(__FILE__, __LINE__, arg)
0319
0320   /* Force the race detector to flush its state. The actual effect depends on
0321    * the implementation of the detector. */
0322 #define _Py_ANNOTATE_FLUSH_STATE() \
0323     AnnotateFlushState(__FILE__, __LINE__)
0324
0325
0326 #else  /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
0327
0328 #define _Py_ANNOTATE_RWLOCK_CREATE(lock) /* empty */
0329 #define _Py_ANNOTATE_RWLOCK_DESTROY(lock) /* empty */
0330 #define _Py_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) /* empty */
0331 #define _Py_ANNOTATE_RWLOCK_RELEASED(lock, is_w) /* empty */
0332 #define _Py_ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) /* */
0333 #define _Py_ANNOTATE_BARRIER_WAIT_BEFORE(barrier) /* empty */
0334 #define _Py_ANNOTATE_BARRIER_WAIT_AFTER(barrier) /* empty */
0335 #define _Py_ANNOTATE_BARRIER_DESTROY(barrier) /* empty */
0336 #define _Py_ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) /* empty */
0337 #define _Py_ANNOTATE_CONDVAR_WAIT(cv) /* empty */
0338 #define _Py_ANNOTATE_CONDVAR_SIGNAL(cv) /* empty */
0339 #define _Py_ANNOTATE_CONDVAR_SIGNAL_ALL(cv) /* empty */
0340 #define _Py_ANNOTATE_HAPPENS_BEFORE(obj) /* empty */
0341 #define _Py_ANNOTATE_HAPPENS_AFTER(obj) /* empty */
0342 #define _Py_ANNOTATE_PUBLISH_MEMORY_RANGE(address, size) /* empty */
0343 #define _Py_ANNOTATE_UNPUBLISH_MEMORY_RANGE(address, size)  /* empty */
0344 #define _Py_ANNOTATE_SWAP_MEMORY_RANGE(address, size)  /* empty */
0345 #define _Py_ANNOTATE_PCQ_CREATE(pcq) /* empty */
0346 #define _Py_ANNOTATE_PCQ_DESTROY(pcq) /* empty */
0347 #define _Py_ANNOTATE_PCQ_PUT(pcq) /* empty */
0348 #define _Py_ANNOTATE_PCQ_GET(pcq) /* empty */
0349 #define _Py_ANNOTATE_NEW_MEMORY(address, size) /* empty */
0350 #define _Py_ANNOTATE_EXPECT_RACE(address, description) /* empty */
0351 #define _Py_ANNOTATE_BENIGN_RACE(address, description) /* empty */
0352 #define _Py_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) /* empty */
0353 #define _Py_ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) /* empty */
0354 #define _Py_ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) /* empty */
0355 #define _Py_ANNOTATE_TRACE_MEMORY(arg) /* empty */
0356 #define _Py_ANNOTATE_THREAD_NAME(name) /* empty */
0357 #define _Py_ANNOTATE_IGNORE_READS_BEGIN() /* empty */
0358 #define _Py_ANNOTATE_IGNORE_READS_END() /* empty */
0359 #define _Py_ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */
0360 #define _Py_ANNOTATE_IGNORE_WRITES_END() /* empty */
0361 #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */
0362 #define _Py_ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */
0363 #define _Py_ANNOTATE_IGNORE_SYNC_BEGIN() /* empty */
0364 #define _Py_ANNOTATE_IGNORE_SYNC_END() /* empty */
0365 #define _Py_ANNOTATE_ENABLE_RACE_DETECTION(enable) /* empty */
0366 #define _Py_ANNOTATE_NO_OP(arg) /* empty */
0367 #define _Py_ANNOTATE_FLUSH_STATE() /* empty */
0368
0369 #endif  /* DYNAMIC_ANNOTATIONS_ENABLED */
0370
0371 /* Use the macros above rather than using these functions directly. */
0372 #ifdef __cplusplus
0373 extern "C" {
0374 #endif
0375 void AnnotateRWLockCreate(const char *file, int line,
0376                           const volatile void *lock);
0377 void AnnotateRWLockDestroy(const char *file, int line,
0378                            const volatile void *lock);
0379 void AnnotateRWLockAcquired(const char *file, int line,
0380                             const volatile void *lock, long is_w);
0381 void AnnotateRWLockReleased(const char *file, int line,
0382                             const volatile void *lock, long is_w);
0383 void AnnotateBarrierInit(const char *file, int line,
0384                          const volatile void *barrier, long count,
0385                          long reinitialization_allowed);
0386 void AnnotateBarrierWaitBefore(const char *file, int line,
0387                                const volatile void *barrier);
0388 void AnnotateBarrierWaitAfter(const char *file, int line,
0389                               const volatile void *barrier);
0390 void AnnotateBarrierDestroy(const char *file, int line,
0391                             const volatile void *barrier);
0392 void AnnotateCondVarWait(const char *file, int line,
0393                          const volatile void *cv,
0394                          const volatile void *lock);
0395 void AnnotateCondVarSignal(const char *file, int line,
0396                            const volatile void *cv);
0397 void AnnotateCondVarSignalAll(const char *file, int line,
0398                               const volatile void *cv);
0399 void AnnotatePublishMemoryRange(const char *file, int line,
0400                                 const volatile void *address,
0401                                 long size);
0402 void AnnotateUnpublishMemoryRange(const char *file, int line,
0403                                   const volatile void *address,
0404                                   long size);
0405 void AnnotatePCQCreate(const char *file, int line,
0406                        const volatile void *pcq);
0407 void AnnotatePCQDestroy(const char *file, int line,
0408                         const volatile void *pcq);
0409 void AnnotatePCQPut(const char *file, int line,
0410                     const volatile void *pcq);
0411 void AnnotatePCQGet(const char *file, int line,
0412                     const volatile void *pcq);
0413 void AnnotateNewMemory(const char *file, int line,
0414                        const volatile void *address,
0415                        long size);
0416 void AnnotateExpectRace(const char *file, int line,
0417                         const volatile void *address,
0418                         const char *description);
0419 void AnnotateBenignRace(const char *file, int line,
0420                         const volatile void *address,
0421                         const char *description);
0422 void AnnotateBenignRaceSized(const char *file, int line,
0423                         const volatile void *address,
0424                         long size,
0425                         const char *description);
0426 void AnnotateMutexIsUsedAsCondVar(const char *file, int line,
0427                                   const volatile void *mu);
0428 void AnnotateTraceMemory(const char *file, int line,
0429                          const volatile void *arg);
0430 void AnnotateThreadName(const char *file, int line,
0431                         const char *name);
0432 void AnnotateIgnoreReadsBegin(const char *file, int line);
0433 void AnnotateIgnoreReadsEnd(const char *file, int line);
0434 void AnnotateIgnoreWritesBegin(const char *file, int line);
0435 void AnnotateIgnoreWritesEnd(const char *file, int line);
0436 void AnnotateEnableRaceDetection(const char *file, int line, int enable);
0437 void AnnotateNoOp(const char *file, int line,
0438                   const volatile void *arg);
0439 void AnnotateFlushState(const char *file, int line);
0440
0441 /* Return non-zero value if running under valgrind.
0442
0443   If "valgrind.h" is included into dynamic_annotations.c,
0444   the regular valgrind mechanism will be used.
0445   See http://valgrind.org/docs/manual/manual-core-adv.html about
0446   RUNNING_ON_VALGRIND and other valgrind "client requests".
0447   The file "valgrind.h" may be obtained by doing
0448      svn co svn://svn.valgrind.org/valgrind/trunk/include
0449
0450   If for some reason you can't use "valgrind.h" or want to fake valgrind,
0451   there are two ways to make this function return non-zero:
0452     - Use environment variable: export RUNNING_ON_VALGRIND=1
0453     - Make your tool intercept the function RunningOnValgrind() and
0454       change its return value.
0455  */
0456 int RunningOnValgrind(void);
0457
0458 #ifdef __cplusplus
0459 }
0460 #endif
0461
0462 #if DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus)
0463
0464   /* _Py_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads.
0465
0466      Instead of doing
0467         _Py_ANNOTATE_IGNORE_READS_BEGIN();
0468         ... = x;
0469         _Py_ANNOTATE_IGNORE_READS_END();
0470      one can use
0471         ... = _Py_ANNOTATE_UNPROTECTED_READ(x); */
0472   template <class T>
0473   inline T _Py_ANNOTATE_UNPROTECTED_READ(const volatile T &x) {
0474     _Py_ANNOTATE_IGNORE_READS_BEGIN();
0475     T res = x;
0476     _Py_ANNOTATE_IGNORE_READS_END();
0477     return res;
0478   }
0479   /* Apply _Py_ANNOTATE_BENIGN_RACE_SIZED to a static variable. */
0480 #define _Py_ANNOTATE_BENIGN_RACE_STATIC(static_var, description)        \
0481     namespace {                                                       \
0482       class static_var ## _annotator {                                \
0483        public:                                                        \
0484         static_var ## _annotator() {                                  \
0485           _Py_ANNOTATE_BENIGN_RACE_SIZED(&static_var,                     \
0486                                       sizeof(static_var),             \
0487             # static_var ": " description);                           \
0488         }                                                             \
0489       };                                                              \
0490       static static_var ## _annotator the ## static_var ## _annotator;\
0491     }
0492 #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
0493
0494 #define _Py_ANNOTATE_UNPROTECTED_READ(x) (x)
0495 #define _Py_ANNOTATE_BENIGN_RACE_STATIC(static_var, description)  /* empty */
0496
0497 #endif /* DYNAMIC_ANNOTATIONS_ENABLED */
0498
0499 #endif  /* __DYNAMIC_ANNOTATIONS_H__ */