third_party/tcmalloc/chromium/src/base/dynamic_annotations.h

   1 /* Copyright (c) 2008, Google Inc.
   2  * All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   8  *     * Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *     * Redistributions in binary form must reproduce the above
  11  * copyright notice, this list of conditions and the following disclaimer
  12  * in the documentation and/or other materials provided with the
  13  * distribution.
  14  *     * Neither the name of Google Inc. nor the names of its
  15  * contributors may be used to endorse or promote products derived from
  16  * this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  * ---
  31  * Author: Kostya Serebryany
  32  */
  33
  34 /* This file defines dynamic annotations for use with dynamic analysis
  35    tool such as valgrind, PIN, etc.
  36
  37    Dynamic annotation is a source code annotation that affects
  38    the generated code (that is, the annotation is not a comment).
  39    Each such annotation is attached to a particular
  40    instruction and/or to a particular object (address) in the program.
  41
  42    The annotations that should be used by users are macros in all upper-case
  43    (e.g., ANNOTATE_NEW_MEMORY).
  44
  45    Actual implementation of these macros may differ depending on the
  46    dynamic analysis tool being used.
  47
  48    See http://code.google.com/p/data-race-test/  for more information.
  49
  50    This file supports the following dynamic analysis tools:
  51    - None (DYNAMIC_ANNOTATIONS_ENABLED is not defined or zero).
  52       Macros are defined empty.
  53    - ThreadSanitizer, Helgrind, DRD (DYNAMIC_ANNOTATIONS_ENABLED is 1).
  54       Macros are defined as calls to non-inlinable empty functions
  55       that are intercepted by Valgrind. */
  56
  57 #ifndef BASE_DYNAMIC_ANNOTATIONS_H_
  58 #define BASE_DYNAMIC_ANNOTATIONS_H_
  59
  60 #ifndef DYNAMIC_ANNOTATIONS_ENABLED
  61 # define DYNAMIC_ANNOTATIONS_ENABLED 0
  62 #endif
  63
  64 #if DYNAMIC_ANNOTATIONS_ENABLED != 0
  65
  66   /* -------------------------------------------------------------
  67      Annotations useful when implementing condition variables such as CondVar,
  68      using conditional critical sections (Await/LockWhen) and when constructing
  69      user-defined synchronization mechanisms.
  70
  71      The annotations ANNOTATE_HAPPENS_BEFORE() and ANNOTATE_HAPPENS_AFTER() can
  72      be used to define happens-before arcs in user-defined synchronization
  73      mechanisms:  the race detector will infer an arc from the former to the
  74      latter when they share the same argument pointer.
  75
  76      Example 1 (reference counting):
  77
  78      void Unref() {
  79        ANNOTATE_HAPPENS_BEFORE(&refcount_);
  80        if (AtomicDecrementByOne(&refcount_) == 0) {
  81          ANNOTATE_HAPPENS_AFTER(&refcount_);
  82          delete this;
  83        }
  84      }
  85
  86      Example 2 (message queue):
  87
  88      void MyQueue::Put(Type *e) {
  89        MutexLock lock(&mu_);
  90        ANNOTATE_HAPPENS_BEFORE(e);
  91        PutElementIntoMyQueue(e);
  92      }
  93
  94      Type *MyQueue::Get() {
  95        MutexLock lock(&mu_);
  96        Type *e = GetElementFromMyQueue();
  97        ANNOTATE_HAPPENS_AFTER(e);
  98        return e;
  99      }
 100
 101      Note: when possible, please use the existing reference counting and message
 102      queue implementations instead of inventing new ones. */
 103
 104   /* Report that wait on the condition variable at address "cv" has succeeded
 105      and the lock at address "lock" is held. */
 106   #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \
 107     AnnotateCondVarWait(__FILE__, __LINE__, cv, lock)
 108
 109   /* Report that wait on the condition variable at "cv" has succeeded.  Variant
 110      w/o lock. */
 111   #define ANNOTATE_CONDVAR_WAIT(cv) \
 112     AnnotateCondVarWait(__FILE__, __LINE__, cv, NULL)
 113
 114   /* Report that we are about to signal on the condition variable at address
 115      "cv". */
 116   #define ANNOTATE_CONDVAR_SIGNAL(cv) \
 117     AnnotateCondVarSignal(__FILE__, __LINE__, cv)
 118
 119   /* Report that we are about to signal_all on the condition variable at "cv". */
 120   #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \
 121     AnnotateCondVarSignalAll(__FILE__, __LINE__, cv)
 122
 123   /* Annotations for user-defined synchronization mechanisms. */
 124   #define ANNOTATE_HAPPENS_BEFORE(obj) ANNOTATE_CONDVAR_SIGNAL(obj)
 125   #define ANNOTATE_HAPPENS_AFTER(obj)  ANNOTATE_CONDVAR_WAIT(obj)
 126
 127   /* Report that the bytes in the range [pointer, pointer+size) are about
 128      to be published safely. The race checker will create a happens-before
 129      arc from the call ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) to
 130      subsequent accesses to this memory.
 131      Note: this annotation may not work properly if the race detector uses
 132      sampling, i.e. does not observe all memory accesses.
 133      */
 134   #define ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \
 135     AnnotatePublishMemoryRange(__FILE__, __LINE__, pointer, size)
 136
 137   /* DEPRECATED. Don't use it. */
 138   #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size) \
 139     AnnotateUnpublishMemoryRange(__FILE__, __LINE__, pointer, size)
 140
 141   /* DEPRECATED. Don't use it. */
 142   #define ANNOTATE_SWAP_MEMORY_RANGE(pointer, size)   \
 143     do {                                              \
 144       ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size); \
 145       ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size);   \
 146     } while (0)
 147
 148   /* Instruct the tool to create a happens-before arc between mu->Unlock() and
 149      mu->Lock(). This annotation may slow down the race detector and hide real
 150      races. Normally it is used only when it would be difficult to annotate each
 151      of the mutex's critical sections individually using the annotations above.
 152      This annotation makes sense only for hybrid race detectors. For pure
 153      happens-before detectors this is a no-op. For more details see
 154      http://code.google.com/p/data-race-test/wiki/PureHappensBeforeVsHybrid . */
 155   #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \
 156     AnnotateMutexIsUsedAsCondVar(__FILE__, __LINE__, mu)
 157
 158   /* Deprecated. Use ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX. */
 159   #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) \
 160     AnnotateMutexIsUsedAsCondVar(__FILE__, __LINE__, mu)
 161
 162   /* -------------------------------------------------------------
 163      Annotations useful when defining memory allocators, or when memory that
 164      was protected in one way starts to be protected in another. */
 165
 166   /* Report that a new memory at "address" of size "size" has been allocated.
 167      This might be used when the memory has been retrieved from a free list and
 168      is about to be reused, or when a the locking discipline for a variable
 169      changes. */
 170   #define ANNOTATE_NEW_MEMORY(address, size) \
 171     AnnotateNewMemory(__FILE__, __LINE__, address, size)
 172
 173   /* -------------------------------------------------------------
 174      Annotations useful when defining FIFO queues that transfer data between
 175      threads. */
 176
 177   /* Report that the producer-consumer queue (such as ProducerConsumerQueue) at
 178      address "pcq" has been created.  The ANNOTATE_PCQ_* annotations
 179      should be used only for FIFO queues.  For non-FIFO queues use
 180      ANNOTATE_HAPPENS_BEFORE (for put) and ANNOTATE_HAPPENS_AFTER (for get). */
 181   #define ANNOTATE_PCQ_CREATE(pcq) \
 182     AnnotatePCQCreate(__FILE__, __LINE__, pcq)
 183
 184   /* Report that the queue at address "pcq" is about to be destroyed. */
 185   #define ANNOTATE_PCQ_DESTROY(pcq) \
 186     AnnotatePCQDestroy(__FILE__, __LINE__, pcq)
 187
 188   /* Report that we are about to put an element into a FIFO queue at address
 189      "pcq". */
 190   #define ANNOTATE_PCQ_PUT(pcq) \
 191     AnnotatePCQPut(__FILE__, __LINE__, pcq)
 192
 193   /* Report that we've just got an element from a FIFO queue at address "pcq". */
 194   #define ANNOTATE_PCQ_GET(pcq) \
 195     AnnotatePCQGet(__FILE__, __LINE__, pcq)
 196
 197   /* -------------------------------------------------------------
 198      Annotations that suppress errors.  It is usually better to express the
 199      program's synchronization using the other annotations, but these can
 200      be used when all else fails. */
 201
 202   /* Report that we may have a benign race at "pointer", with size
 203      "sizeof(*(pointer))". "pointer" must be a non-void* pointer.  Insert at the
 204      point where "pointer" has been allocated, preferably close to the point
 205      where the race happens.  See also ANNOTATE_BENIGN_RACE_STATIC. */
 206   #define ANNOTATE_BENIGN_RACE(pointer, description) \
 207     AnnotateBenignRaceSized(__FILE__, __LINE__, pointer, \
 208                             sizeof(*(pointer)), description)
 209
 210   /* Same as ANNOTATE_BENIGN_RACE(address, description), but applies to
 211      the memory range [address, address+size). */
 212   #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \
 213     AnnotateBenignRaceSized(__FILE__, __LINE__, address, size, description)
 214
 215   /* Request the analysis tool to ignore all reads in the current thread
 216      until ANNOTATE_IGNORE_READS_END is called.
 217      Useful to ignore intentional racey reads, while still checking
 218      other reads and all writes.
 219      See also ANNOTATE_UNPROTECTED_READ. */
 220   #define ANNOTATE_IGNORE_READS_BEGIN() \
 221     AnnotateIgnoreReadsBegin(__FILE__, __LINE__)
 222
 223   /* Stop ignoring reads. */
 224   #define ANNOTATE_IGNORE_READS_END() \
 225     AnnotateIgnoreReadsEnd(__FILE__, __LINE__)
 226
 227   /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */
 228   #define ANNOTATE_IGNORE_WRITES_BEGIN() \
 229     AnnotateIgnoreWritesBegin(__FILE__, __LINE__)
 230
 231   /* Stop ignoring writes. */
 232   #define ANNOTATE_IGNORE_WRITES_END() \
 233     AnnotateIgnoreWritesEnd(__FILE__, __LINE__)
 234
 235   /* Start ignoring all memory accesses (reads and writes). */
 236   #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
 237     do {\
 238       ANNOTATE_IGNORE_READS_BEGIN();\
 239       ANNOTATE_IGNORE_WRITES_BEGIN();\
 240     }while(0)\
 241
 242   /* Stop ignoring all memory accesses. */
 243   #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \
 244     do {\
 245       ANNOTATE_IGNORE_WRITES_END();\
 246       ANNOTATE_IGNORE_READS_END();\
 247     }while(0)\
 248
 249   /* Enable (enable!=0) or disable (enable==0) race detection for all threads.
 250      This annotation could be useful if you want to skip expensive race analysis
 251      during some period of program execution, e.g. during initialization. */
 252   #define ANNOTATE_ENABLE_RACE_DETECTION(enable) \
 253     AnnotateEnableRaceDetection(__FILE__, __LINE__, enable)
 254
 255   /* -------------------------------------------------------------
 256      Annotations useful for debugging. */
 257
 258   /* Request to trace every access to "address". */
 259   #define ANNOTATE_TRACE_MEMORY(address) \
 260     AnnotateTraceMemory(__FILE__, __LINE__, address)
 261
 262   /* Report the current thread name to a race detector. */
 263   #define ANNOTATE_THREAD_NAME(name) \
 264     AnnotateThreadName(__FILE__, __LINE__, name)
 265
 266   /* -------------------------------------------------------------
 267      Annotations useful when implementing locks.  They are not
 268      normally needed by modules that merely use locks.
 269      The "lock" argument is a pointer to the lock object. */
 270
 271   /* Report that a lock has been created at address "lock". */
 272   #define ANNOTATE_RWLOCK_CREATE(lock) \
 273     AnnotateRWLockCreate(__FILE__, __LINE__, lock)
 274
 275   /* Report that the lock at address "lock" is about to be destroyed. */
 276   #define ANNOTATE_RWLOCK_DESTROY(lock) \
 277     AnnotateRWLockDestroy(__FILE__, __LINE__, lock)
 278
 279   /* Report that the lock at address "lock" has been acquired.
 280      is_w=1 for writer lock, is_w=0 for reader lock. */
 281   #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \
 282     AnnotateRWLockAcquired(__FILE__, __LINE__, lock, is_w)
 283
 284   /* Report that the lock at address "lock" is about to be released. */
 285   #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \
 286     AnnotateRWLockReleased(__FILE__, __LINE__, lock, is_w)
 287
 288   /* -------------------------------------------------------------
 289      Annotations useful when implementing barriers.  They are not
 290      normally needed by modules that merely use barriers.
 291      The "barrier" argument is a pointer to the barrier object. */
 292
 293   /* Report that the "barrier" has been initialized with initial "count".
 294    If 'reinitialization_allowed' is true, initialization is allowed to happen
 295    multiple times w/o calling barrier_destroy() */
 296   #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \
 297     AnnotateBarrierInit(__FILE__, __LINE__, barrier, count, \
 298                         reinitialization_allowed)
 299
 300   /* Report that we are about to enter barrier_wait("barrier"). */
 301   #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \
 302     AnnotateBarrierWaitBefore(__FILE__, __LINE__, barrier)
 303
 304   /* Report that we just exited barrier_wait("barrier"). */
 305   #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) \
 306     AnnotateBarrierWaitAfter(__FILE__, __LINE__, barrier)
 307
 308   /* Report that the "barrier" has been destroyed. */
 309   #define ANNOTATE_BARRIER_DESTROY(barrier) \
 310     AnnotateBarrierDestroy(__FILE__, __LINE__, barrier)
 311
 312   /* -------------------------------------------------------------
 313      Annotations useful for testing race detectors. */
 314
 315   /* Report that we expect a race on the variable at "address".
 316      Use only in unit tests for a race detector. */
 317   #define ANNOTATE_EXPECT_RACE(address, description) \
 318     AnnotateExpectRace(__FILE__, __LINE__, address, description)
 319
 320   /* A no-op. Insert where you like to test the interceptors. */
 321   #define ANNOTATE_NO_OP(arg) \
 322     AnnotateNoOp(__FILE__, __LINE__, arg)
 323
 324   /* Force the race detector to flush its state. The actual effect depends on
 325    * the implementation of the detector. */
 326   #define ANNOTATE_FLUSH_STATE() \
 327     AnnotateFlushState(__FILE__, __LINE__)
 328
 329
 330 #else  /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
 331
 332   #define ANNOTATE_RWLOCK_CREATE(lock) /* empty */
 333   #define ANNOTATE_RWLOCK_DESTROY(lock) /* empty */
 334   #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) /* empty */
 335   #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) /* empty */
 336   #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) /* */
 337   #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) /* empty */
 338   #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) /* empty */
 339   #define ANNOTATE_BARRIER_DESTROY(barrier) /* empty */
 340   #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) /* empty */
 341   #define ANNOTATE_CONDVAR_WAIT(cv) /* empty */
 342   #define ANNOTATE_CONDVAR_SIGNAL(cv) /* empty */
 343   #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) /* empty */
 344   #define ANNOTATE_HAPPENS_BEFORE(obj) /* empty */
 345   #define ANNOTATE_HAPPENS_AFTER(obj) /* empty */
 346   #define ANNOTATE_PUBLISH_MEMORY_RANGE(address, size) /* empty */
 347   #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(address, size)  /* empty */
 348   #define ANNOTATE_SWAP_MEMORY_RANGE(address, size)  /* empty */
 349   #define ANNOTATE_PCQ_CREATE(pcq) /* empty */
 350   #define ANNOTATE_PCQ_DESTROY(pcq) /* empty */
 351   #define ANNOTATE_PCQ_PUT(pcq) /* empty */
 352   #define ANNOTATE_PCQ_GET(pcq) /* empty */
 353   #define ANNOTATE_NEW_MEMORY(address, size) /* empty */
 354   #define ANNOTATE_EXPECT_RACE(address, description) /* empty */
 355   #define ANNOTATE_BENIGN_RACE(address, description) /* empty */
 356   #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) /* empty */
 357   #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) /* empty */
 358   #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) /* empty */
 359   #define ANNOTATE_TRACE_MEMORY(arg) /* empty */
 360   #define ANNOTATE_THREAD_NAME(name) /* empty */
 361   #define ANNOTATE_IGNORE_READS_BEGIN() /* empty */
 362   #define ANNOTATE_IGNORE_READS_END() /* empty */
 363   #define ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */
 364   #define ANNOTATE_IGNORE_WRITES_END() /* empty */
 365   #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */
 366   #define ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */
 367   #define ANNOTATE_ENABLE_RACE_DETECTION(enable) /* empty */
 368   #define ANNOTATE_NO_OP(arg) /* empty */
 369   #define ANNOTATE_FLUSH_STATE() /* empty */
 370
 371 #endif  /* DYNAMIC_ANNOTATIONS_ENABLED */
 372
 373 /* Macro definitions for GCC attributes that allow static thread safety
 374    analysis to recognize and use some of the dynamic annotations as
 375    escape hatches.
 376    TODO(lcwu): remove the check for __SUPPORT_DYN_ANNOTATION__ once the
 377    default crosstool/GCC supports these GCC attributes.  */
 378
 379 #define ANNOTALYSIS_STATIC_INLINE
 380 #define ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY ;
 381 #define ANNOTALYSIS_IGNORE_READS_BEGIN
 382 #define ANNOTALYSIS_IGNORE_READS_END
 383 #define ANNOTALYSIS_IGNORE_WRITES_BEGIN
 384 #define ANNOTALYSIS_IGNORE_WRITES_END
 385 #define ANNOTALYSIS_UNPROTECTED_READ
 386
 387 #if defined(__GNUC__) && (!defined(SWIG)) && (!defined(__clang__)) && \
 388     defined(__SUPPORT_TS_ANNOTATION__) && defined(__SUPPORT_DYN_ANNOTATION__)
 389
 390 #if DYNAMIC_ANNOTATIONS_ENABLED == 0
 391 #define ANNOTALYSIS_ONLY 1
 392 #undef ANNOTALYSIS_STATIC_INLINE
 393 #define ANNOTALYSIS_STATIC_INLINE static inline
 394 #undef ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 395 #define ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY { (void)file; (void)line; }
 396 #endif
 397
 398 /* Only emit attributes when annotalysis is enabled. */
 399 #if defined(__SUPPORT_TS_ANNOTATION__) && defined(__SUPPORT_DYN_ANNOTATION__)
 400 #undef  ANNOTALYSIS_IGNORE_READS_BEGIN
 401 #define ANNOTALYSIS_IGNORE_READS_BEGIN  __attribute__ ((ignore_reads_begin))
 402 #undef  ANNOTALYSIS_IGNORE_READS_END
 403 #define ANNOTALYSIS_IGNORE_READS_END    __attribute__ ((ignore_reads_end))
 404 #undef  ANNOTALYSIS_IGNORE_WRITES_BEGIN
 405 #define ANNOTALYSIS_IGNORE_WRITES_BEGIN __attribute__ ((ignore_writes_begin))
 406 #undef  ANNOTALYSIS_IGNORE_WRITES_END
 407 #define ANNOTALYSIS_IGNORE_WRITES_END   __attribute__ ((ignore_writes_end))
 408 #undef  ANNOTALYSIS_UNPROTECTED_READ
 409 #define ANNOTALYSIS_UNPROTECTED_READ    __attribute__ ((unprotected_read))
 410 #endif
 411
 412 #endif // defined(__GNUC__) && (!defined(SWIG)) && (!defined(__clang__))
 413
 414 /* Use the macros above rather than using these functions directly. */
 415 #ifdef __cplusplus
 416 extern "C" {
 417 #endif
 418 void AnnotateRWLockCreate(const char *file, int line,
 419                           const volatile void *lock);
 420 void AnnotateRWLockDestroy(const char *file, int line,
 421                            const volatile void *lock);
 422 void AnnotateRWLockAcquired(const char *file, int line,
 423                             const volatile void *lock, long is_w);
 424 void AnnotateRWLockReleased(const char *file, int line,
 425                             const volatile void *lock, long is_w);
 426 void AnnotateBarrierInit(const char *file, int line,
 427                          const volatile void *barrier, long count,
 428                          long reinitialization_allowed);
 429 void AnnotateBarrierWaitBefore(const char *file, int line,
 430                                const volatile void *barrier);
 431 void AnnotateBarrierWaitAfter(const char *file, int line,
 432                               const volatile void *barrier);
 433 void AnnotateBarrierDestroy(const char *file, int line,
 434                             const volatile void *barrier);
 435 void AnnotateCondVarWait(const char *file, int line,
 436                          const volatile void *cv,
 437                          const volatile void *lock);
 438 void AnnotateCondVarSignal(const char *file, int line,
 439                            const volatile void *cv);
 440 void AnnotateCondVarSignalAll(const char *file, int line,
 441                               const volatile void *cv);
 442 void AnnotatePublishMemoryRange(const char *file, int line,
 443                                 const volatile void *address,
 444                                 long size);
 445 void AnnotateUnpublishMemoryRange(const char *file, int line,
 446                                   const volatile void *address,
 447                                   long size);
 448 void AnnotatePCQCreate(const char *file, int line,
 449                        const volatile void *pcq);
 450 void AnnotatePCQDestroy(const char *file, int line,
 451                         const volatile void *pcq);
 452 void AnnotatePCQPut(const char *file, int line,
 453                     const volatile void *pcq);
 454 void AnnotatePCQGet(const char *file, int line,
 455                     const volatile void *pcq);
 456 void AnnotateNewMemory(const char *file, int line,
 457                        const volatile void *address,
 458                        long size);
 459 void AnnotateExpectRace(const char *file, int line,
 460                         const volatile void *address,
 461                         const char *description);
 462 void AnnotateBenignRace(const char *file, int line,
 463                         const volatile void *address,
 464                         const char *description);
 465 void AnnotateBenignRaceSized(const char *file, int line,
 466                         const volatile void *address,
 467                         long size,
 468                         const char *description);
 469 void AnnotateMutexIsUsedAsCondVar(const char *file, int line,
 470                                   const volatile void *mu);
 471 void AnnotateTraceMemory(const char *file, int line,
 472                          const volatile void *arg);
 473 void AnnotateThreadName(const char *file, int line,
 474                         const char *name);
 475 ANNOTALYSIS_STATIC_INLINE
 476 void AnnotateIgnoreReadsBegin(const char *file, int line)
 477     ANNOTALYSIS_IGNORE_READS_BEGIN ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 478 ANNOTALYSIS_STATIC_INLINE
 479 void AnnotateIgnoreReadsEnd(const char *file, int line)
 480     ANNOTALYSIS_IGNORE_READS_END ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 481 ANNOTALYSIS_STATIC_INLINE
 482 void AnnotateIgnoreWritesBegin(const char *file, int line)
 483     ANNOTALYSIS_IGNORE_WRITES_BEGIN ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 484 ANNOTALYSIS_STATIC_INLINE
 485 void AnnotateIgnoreWritesEnd(const char *file, int line)
 486     ANNOTALYSIS_IGNORE_WRITES_END ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 487 void AnnotateEnableRaceDetection(const char *file, int line, int enable);
 488 void AnnotateNoOp(const char *file, int line,
 489                   const volatile void *arg);
 490 void AnnotateFlushState(const char *file, int line);
 491
 492 /* Return non-zero value if running under valgrind.
 493
 494   If "valgrind.h" is included into dynamic_annotations.c,
 495   the regular valgrind mechanism will be used.
 496   See http://valgrind.org/docs/manual/manual-core-adv.html about
 497   RUNNING_ON_VALGRIND and other valgrind "client requests".
 498   The file "valgrind.h" may be obtained by doing
 499      svn co svn://svn.valgrind.org/valgrind/trunk/include
 500
 501   If for some reason you can't use "valgrind.h" or want to fake valgrind,
 502   there are two ways to make this function return non-zero:
 503     - Use environment variable: export RUNNING_ON_VALGRIND=1
 504     - Make your tool intercept the function RunningOnValgrind() and
 505       change its return value.
 506  */
 507 int RunningOnValgrind(void);
 508
 509 /* ValgrindSlowdown returns:
 510     * 1.0, if (RunningOnValgrind() == 0)
 511     * 50.0, if (RunningOnValgrind() != 0 && getenv("VALGRIND_SLOWDOWN") == NULL)
 512     * atof(getenv("VALGRIND_SLOWDOWN")) otherwise
 513    This function can be used to scale timeout values:
 514    EXAMPLE:
 515    for (;;) {
 516      DoExpensiveBackgroundTask();
 517      SleepForSeconds(5 * ValgrindSlowdown());
 518    }
 519  */
 520 double ValgrindSlowdown(void);
 521
 522 #ifdef __cplusplus
 523 }
 524 #endif
 525
 526 #if DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus)
 527
 528   /* ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads.
 529
 530      Instead of doing
 531         ANNOTATE_IGNORE_READS_BEGIN();
 532         ... = x;
 533         ANNOTATE_IGNORE_READS_END();
 534      one can use
 535         ... = ANNOTATE_UNPROTECTED_READ(x); */
 536   template <class T>
 537   inline T ANNOTATE_UNPROTECTED_READ(const volatile T &x)
 538       ANNOTALYSIS_UNPROTECTED_READ {
 539     ANNOTATE_IGNORE_READS_BEGIN();
 540     T res = x;
 541     ANNOTATE_IGNORE_READS_END();
 542     return res;
 543   }
 544   /* Apply ANNOTATE_BENIGN_RACE_SIZED to a static variable. */
 545   #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description)        \
 546     namespace {                                                       \
 547       class static_var ## _annotator {                                \
 548        public:                                                        \
 549         static_var ## _annotator() {                                  \
 550           ANNOTATE_BENIGN_RACE_SIZED(&static_var,                     \
 551                                       sizeof(static_var),             \
 552             # static_var ": " description);                           \
 553         }                                                             \
 554       };                                                              \
 555       static static_var ## _annotator the ## static_var ## _annotator;\
 556     }
 557 #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
 558
 559   #define ANNOTATE_UNPROTECTED_READ(x) (x)
 560   #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description)  /* empty */
 561
 562 #endif /* DYNAMIC_ANNOTATIONS_ENABLED */
 563
 564 /* Annotalysis, a GCC based static analyzer, is able to understand and use
 565    some of the dynamic annotations defined in this file. However, dynamic
 566    annotations are usually disabled in the opt mode (to avoid additional
 567    runtime overheads) while Annotalysis only works in the opt mode.
 568    In order for Annotalysis to use these dynamic annotations when they
 569    are disabled, we re-define these annotations here. Note that unlike the
 570    original macro definitions above, these macros are expanded to calls to
 571    static inline functions so that the compiler will be able to remove the
 572    calls after the analysis. */
 573
 574 #ifdef ANNOTALYSIS_ONLY
 575
 576   #undef ANNOTALYSIS_ONLY
 577
 578   /* Undefine and re-define the macros that the static analyzer understands. */
 579   #undef ANNOTATE_IGNORE_READS_BEGIN
 580   #define ANNOTATE_IGNORE_READS_BEGIN()           \
 581     AnnotateIgnoreReadsBegin(__FILE__, __LINE__)
 582
 583   #undef ANNOTATE_IGNORE_READS_END
 584   #define ANNOTATE_IGNORE_READS_END()             \
 585     AnnotateIgnoreReadsEnd(__FILE__, __LINE__)
 586
 587   #undef ANNOTATE_IGNORE_WRITES_BEGIN
 588   #define ANNOTATE_IGNORE_WRITES_BEGIN()          \
 589     AnnotateIgnoreWritesBegin(__FILE__, __LINE__)
 590
 591   #undef ANNOTATE_IGNORE_WRITES_END
 592   #define ANNOTATE_IGNORE_WRITES_END()            \
 593     AnnotateIgnoreWritesEnd(__FILE__, __LINE__)
 594
 595   #undef ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN
 596   #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN()       \
 597     do {                                                 \
 598       ANNOTATE_IGNORE_READS_BEGIN();                     \
 599       ANNOTATE_IGNORE_WRITES_BEGIN();                    \
 600     }while(0)                                            \
 601
 602   #undef ANNOTATE_IGNORE_READS_AND_WRITES_END
 603   #define ANNOTATE_IGNORE_READS_AND_WRITES_END()  \
 604     do {                                          \
 605       ANNOTATE_IGNORE_WRITES_END();               \
 606       ANNOTATE_IGNORE_READS_END();                \
 607     }while(0)                                     \
 608
 609   #if defined(__cplusplus)
 610     #undef ANNOTATE_UNPROTECTED_READ
 611     template <class T>
 612     inline T ANNOTATE_UNPROTECTED_READ(const volatile T &x)
 613          ANNOTALYSIS_UNPROTECTED_READ {
 614       ANNOTATE_IGNORE_READS_BEGIN();
 615       T res = x;
 616       ANNOTATE_IGNORE_READS_END();
 617       return res;
 618     }
 619   #endif /* __cplusplus */
 620
 621 #endif /* ANNOTALYSIS_ONLY */
 622
 623 /* Undefine the macros intended only in this file. */
 624 #undef ANNOTALYSIS_STATIC_INLINE
 625 #undef ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY
 626
 627 #endif  /* BASE_DYNAMIC_ANNOTATIONS_H_ */