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