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 416extern "C" { 417#endif 418void AnnotateRWLockCreate(const char *file, int line, 419 const volatile void *lock); 420void AnnotateRWLockDestroy(const char *file, int line, 421 const volatile void *lock); 422void AnnotateRWLockAcquired(const char *file, int line, 423 const volatile void *lock, long is_w); 424void AnnotateRWLockReleased(const char *file, int line, 425 const volatile void *lock, long is_w); 426void AnnotateBarrierInit(const char *file, int line, 427 const volatile void *barrier, long count, 428 long reinitialization_allowed); 429void AnnotateBarrierWaitBefore(const char *file, int line, 430 const volatile void *barrier); 431void AnnotateBarrierWaitAfter(const char *file, int line, 432 const volatile void *barrier); 433void AnnotateBarrierDestroy(const char *file, int line, 434 const volatile void *barrier); 435void AnnotateCondVarWait(const char *file, int line, 436 const volatile void *cv, 437 const volatile void *lock); 438void AnnotateCondVarSignal(const char *file, int line, 439 const volatile void *cv); 440void AnnotateCondVarSignalAll(const char *file, int line, 441 const volatile void *cv); 442void AnnotatePublishMemoryRange(const char *file, int line, 443 const volatile void *address, 444 long size); 445void AnnotateUnpublishMemoryRange(const char *file, int line, 446 const volatile void *address, 447 long size); 448void AnnotatePCQCreate(const char *file, int line, 449 const volatile void *pcq); 450void AnnotatePCQDestroy(const char *file, int line, 451 const volatile void *pcq); 452void AnnotatePCQPut(const char *file, int line, 453 const volatile void *pcq); 454void AnnotatePCQGet(const char *file, int line, 455 const volatile void *pcq); 456void AnnotateNewMemory(const char *file, int line, 457 const volatile void *address, 458 long size); 459void AnnotateExpectRace(const char *file, int line, 460 const volatile void *address, 461 const char *description); 462void AnnotateBenignRace(const char *file, int line, 463 const volatile void *address, 464 const char *description); 465void AnnotateBenignRaceSized(const char *file, int line, 466 const volatile void *address, 467 long size, 468 const char *description); 469void AnnotateMutexIsUsedAsCondVar(const char *file, int line, 470 const volatile void *mu); 471void AnnotateTraceMemory(const char *file, int line, 472 const volatile void *arg); 473void AnnotateThreadName(const char *file, int line, 474 const char *name); 475ANNOTALYSIS_STATIC_INLINE 476void AnnotateIgnoreReadsBegin(const char *file, int line) 477 ANNOTALYSIS_IGNORE_READS_BEGIN ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY 478ANNOTALYSIS_STATIC_INLINE 479void AnnotateIgnoreReadsEnd(const char *file, int line) 480 ANNOTALYSIS_IGNORE_READS_END ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY 481ANNOTALYSIS_STATIC_INLINE 482void AnnotateIgnoreWritesBegin(const char *file, int line) 483 ANNOTALYSIS_IGNORE_WRITES_BEGIN ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY 484ANNOTALYSIS_STATIC_INLINE 485void AnnotateIgnoreWritesEnd(const char *file, int line) 486 ANNOTALYSIS_IGNORE_WRITES_END ANNOTALYSIS_SEMICOLON_OR_EMPTY_BODY 487void AnnotateEnableRaceDetection(const char *file, int line, int enable); 488void AnnotateNoOp(const char *file, int line, 489 const volatile void *arg); 490void 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 */ 507int 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 */ 520double 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_ */ 628