1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 // This file defines dynamic annotations for use with dynamic analysis tool
16 // such as valgrind, PIN, etc.
17 //
18 // Dynamic annotation is a source code annotation that affects the generated
19 // code (that is, the annotation is not a comment). Each such annotation is
20 // attached to a particular instruction and/or to a particular object (address)
21 // in the program.
22 //
23 // The annotations that should be used by users are macros in all upper-case
24 // (e.g., ABSL_ANNOTATE_THREAD_NAME).
25 //
26 // Actual implementation of these macros may differ depending on the dynamic
27 // analysis tool being used.
28 //
29 // This file supports the following configurations:
30 // - Dynamic Annotations enabled (with static thread-safety warnings disabled).
31 // In this case, macros expand to functions implemented by Thread Sanitizer,
32 // when building with TSan. When not provided an external implementation,
33 // dynamic_annotations.cc provides no-op implementations.
34 //
35 // - Static Clang thread-safety warnings enabled.
36 // When building with a Clang compiler that supports thread-safety warnings,
37 // a subset of annotations can be statically-checked at compile-time. We
38 // expand these macros to static-inline functions that can be analyzed for
39 // thread-safety, but afterwards elided when building the final binary.
40 //
41 // - All annotations are disabled.
42 // If neither Dynamic Annotations nor Clang thread-safety warnings are
43 // enabled, then all annotation-macros expand to empty.
44
45 #ifndef ABSL_BASE_DYNAMIC_ANNOTATIONS_H_
46 #define ABSL_BASE_DYNAMIC_ANNOTATIONS_H_
47
48 #include <stddef.h>
49
50 #include "absl/base/attributes.h"
51 #include "absl/base/config.h"
52 #ifdef __cplusplus
53 #include "absl/base/macros.h"
54 #endif
55
56 // TODO(rogeeff): Remove after the backward compatibility period.
57 #include "absl/base/internal/dynamic_annotations.h" // IWYU pragma: export
58
59 // -------------------------------------------------------------------------
60 // Decide which features are enabled.
61
62 #ifdef ABSL_HAVE_THREAD_SANITIZER
63
64 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 1
65 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 1
66 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 1
67 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0
68 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 1
69
70 #else
71
72 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 0
73 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 0
74 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 0
75
76 // Clang provides limited support for static thread-safety analysis through a
77 // feature called Annotalysis. We configure macro-definitions according to
78 // whether Annotalysis support is available. When running in opt-mode, GCC
79 // will issue a warning, if these attributes are compiled. Only include them
80 // when compiling using Clang.
81
82 #if defined(__clang__)
83 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 1
84 #if !defined(SWIG)
85 #define ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED 1
86 #endif
87 #else
88 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0
89 #endif
90
91 // Read/write annotations are enabled in Annotalysis mode; disabled otherwise.
92 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED \
93 ABSL_INTERNAL_ANNOTALYSIS_ENABLED
94
95 #endif // ABSL_HAVE_THREAD_SANITIZER
96
97 #ifdef __cplusplus
98 #define ABSL_INTERNAL_BEGIN_EXTERN_C extern "C" {
99 #define ABSL_INTERNAL_END_EXTERN_C } // extern "C"
100 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) ::F
101 #define ABSL_INTERNAL_STATIC_INLINE inline
102 #else
103 #define ABSL_INTERNAL_BEGIN_EXTERN_C // empty
104 #define ABSL_INTERNAL_END_EXTERN_C // empty
105 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) F
106 #define ABSL_INTERNAL_STATIC_INLINE static inline
107 #endif
108
109 // -------------------------------------------------------------------------
110 // Define race annotations.
111
112 #if ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 1
113 // Some of the symbols used in this section (e.g. AnnotateBenignRaceSized) are
114 // defined by the compiler-based santizer implementation, not by the Abseil
115 // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL.
116
117 // -------------------------------------------------------------
118 // Annotations that suppress errors. It is usually better to express the
119 // program's synchronization using the other annotations, but these can be used
120 // when all else fails.
121
122 // Report that we may have a benign race at `pointer`, with size
123 // "sizeof(*(pointer))". `pointer` must be a non-void* pointer. Insert at the
124 // point where `pointer` has been allocated, preferably close to the point
125 // where the race happens. See also ABSL_ANNOTATE_BENIGN_RACE_STATIC.
126 #define ABSL_ANNOTATE_BENIGN_RACE(pointer, description) \
127 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \
128 (__FILE__, __LINE__, pointer, sizeof(*(pointer)), description)
129
130 // Same as ABSL_ANNOTATE_BENIGN_RACE(`address`, `description`), but applies to
131 // the memory range [`address`, `address`+`size`).
132 #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \
133 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \
134 (__FILE__, __LINE__, address, size, description)
135
136 // Enable (`enable`!=0) or disable (`enable`==0) race detection for all threads.
137 // This annotation could be useful if you want to skip expensive race analysis
138 // during some period of program execution, e.g. during initialization.
139 #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) \
140 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateEnableRaceDetection) \
141 (__FILE__, __LINE__, enable)
142
143 // -------------------------------------------------------------
144 // Annotations useful for debugging.
145
146 // Report the current thread `name` to a race detector.
147 #define ABSL_ANNOTATE_THREAD_NAME(name) \
148 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateThreadName)(__FILE__, __LINE__, name)
149
150 // -------------------------------------------------------------
151 // Annotations useful when implementing locks. They are not normally needed by
152 // modules that merely use locks. The `lock` argument is a pointer to the lock
153 // object.
154
155 // Report that a lock has been created at address `lock`.
156 #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) \
157 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreate)(__FILE__, __LINE__, lock)
158
159 // Report that a linker initialized lock has been created at address `lock`.
160 #ifdef ABSL_HAVE_THREAD_SANITIZER
161 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \
162 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreateStatic) \
163 (__FILE__, __LINE__, lock)
164 #else
165 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) \
166 ABSL_ANNOTATE_RWLOCK_CREATE(lock)
167 #endif
168
169 // Report that the lock at address `lock` is about to be destroyed.
170 #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) \
171 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockDestroy)(__FILE__, __LINE__, lock)
172
173 // Report that the lock at address `lock` has been acquired.
174 // `is_w`=1 for writer lock, `is_w`=0 for reader lock.
175 #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \
176 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockAcquired) \
177 (__FILE__, __LINE__, lock, is_w)
178
179 // Report that the lock at address `lock` is about to be released.
180 // `is_w`=1 for writer lock, `is_w`=0 for reader lock.
181 #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) \
182 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockReleased) \
183 (__FILE__, __LINE__, lock, is_w)
184
185 // Apply ABSL_ANNOTATE_BENIGN_RACE_SIZED to a static variable `static_var`.
186 #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \
187 namespace { \
188 class static_var##_annotator { \
189 public: \
190 static_var##_annotator() { \
191 ABSL_ANNOTATE_BENIGN_RACE_SIZED(&static_var, sizeof(static_var), \
192 #static_var ": " description); \
193 } \
194 }; \
195 static static_var##_annotator the##static_var##_annotator; \
196 } // namespace
197
198 // Function prototypes of annotations provided by the compiler-based sanitizer
199 // implementation.
200 ABSL_INTERNAL_BEGIN_EXTERN_C
201 void AnnotateRWLockCreate(const char* file, int line,
202 const volatile void* lock);
203 void AnnotateRWLockCreateStatic(const char* file, int line,
204 const volatile void* lock);
205 void AnnotateRWLockDestroy(const char* file, int line,
206 const volatile void* lock);
207 void AnnotateRWLockAcquired(const char* file, int line,
208 const volatile void* lock, long is_w); // NOLINT
209 void AnnotateRWLockReleased(const char* file, int line,
210 const volatile void* lock, long is_w); // NOLINT
211 void AnnotateBenignRace(const char* file, int line,
212 const volatile void* address, const char* description);
213 void AnnotateBenignRaceSized(const char* file, int line,
214 const volatile void* address, size_t size,
215 const char* description);
216 void AnnotateThreadName(const char* file, int line, const char* name);
217 void AnnotateEnableRaceDetection(const char* file, int line, int enable);
218 ABSL_INTERNAL_END_EXTERN_C
219
220 #else // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 0
221
222 #define ABSL_ANNOTATE_RWLOCK_CREATE(lock) // empty
223 #define ABSL_ANNOTATE_RWLOCK_CREATE_STATIC(lock) // empty
224 #define ABSL_ANNOTATE_RWLOCK_DESTROY(lock) // empty
225 #define ABSL_ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) // empty
226 #define ABSL_ANNOTATE_RWLOCK_RELEASED(lock, is_w) // empty
227 #define ABSL_ANNOTATE_BENIGN_RACE(address, description) // empty
228 #define ABSL_ANNOTATE_BENIGN_RACE_SIZED(address, size, description) // empty
229 #define ABSL_ANNOTATE_THREAD_NAME(name) // empty
230 #define ABSL_ANNOTATE_ENABLE_RACE_DETECTION(enable) // empty
231 #define ABSL_ANNOTATE_BENIGN_RACE_STATIC(static_var, description) // empty
232
233 #endif // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED
234
235 // -------------------------------------------------------------------------
236 // Define memory annotations.
237
238 #ifdef ABSL_HAVE_MEMORY_SANITIZER
239
240 #include <sanitizer/msan_interface.h>
241
242 #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \
243 __msan_unpoison(address, size)
244
245 #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \
246 __msan_allocated_memory(address, size)
247
248 #else // !defined(ABSL_HAVE_MEMORY_SANITIZER)
249
250 // TODO(rogeeff): remove this branch
251 #ifdef ABSL_HAVE_THREAD_SANITIZER
252 #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \
253 do { \
254 (void)(address); \
255 (void)(size); \
256 } while (0)
257 #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \
258 do { \
259 (void)(address); \
260 (void)(size); \
261 } while (0)
262 #else
263
264 #define ABSL_ANNOTATE_MEMORY_IS_INITIALIZED(address, size) // empty
265 #define ABSL_ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) // empty
266
267 #endif
268
269 #endif // ABSL_HAVE_MEMORY_SANITIZER
270
271 // -------------------------------------------------------------------------
272 // Define IGNORE_READS_BEGIN/_END attributes.
273
274 #if defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED)
275
276 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE \
277 __attribute((exclusive_lock_function("*")))
278 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE \
279 __attribute((unlock_function("*")))
280
281 #else // !defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED)
282
283 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE // empty
284 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE // empty
285
286 #endif // defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED)
287
288 // -------------------------------------------------------------------------
289 // Define IGNORE_READS_BEGIN/_END annotations.
290
291 #if ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED == 1
292 // Some of the symbols used in this section (e.g. AnnotateIgnoreReadsBegin) are
293 // defined by the compiler-based implementation, not by the Abseil
294 // library. Therefore they do not use ABSL_INTERNAL_C_SYMBOL.
295
296 // Request the analysis tool to ignore all reads in the current thread until
297 // ABSL_ANNOTATE_IGNORE_READS_END is called. Useful to ignore intentional racey
298 // reads, while still checking other reads and all writes.
299 // See also ABSL_ANNOTATE_UNPROTECTED_READ.
300 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \
301 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsBegin) \
302 (__FILE__, __LINE__)
303
304 // Stop ignoring reads.
305 #define ABSL_ANNOTATE_IGNORE_READS_END() \
306 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsEnd) \
307 (__FILE__, __LINE__)
308
309 // Function prototypes of annotations provided by the compiler-based sanitizer
310 // implementation.
311 ABSL_INTERNAL_BEGIN_EXTERN_C
312 void AnnotateIgnoreReadsBegin(const char* file, int line)
313 ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE;
314 void AnnotateIgnoreReadsEnd(const char* file,
315 int line) ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE;
316 ABSL_INTERNAL_END_EXTERN_C
317
318 #elif defined(ABSL_INTERNAL_ANNOTALYSIS_ENABLED)
319
320 // When Annotalysis is enabled without Dynamic Annotations, the use of
321 // static-inline functions allows the annotations to be read at compile-time,
322 // while still letting the compiler elide the functions from the final build.
323 //
324 // TODO(delesley) -- The exclusive lock here ignores writes as well, but
325 // allows IGNORE_READS_AND_WRITES to work properly.
326
327 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() \
328 ABSL_INTERNAL_GLOBAL_SCOPED( \
329 ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsBegin)) \
330 ()
331
332 #define ABSL_ANNOTATE_IGNORE_READS_END() \
333 ABSL_INTERNAL_GLOBAL_SCOPED( \
334 ABSL_INTERNAL_C_SYMBOL(AbslInternalAnnotateIgnoreReadsEnd)) \
335 ()
336
337 ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL(
338 AbslInternalAnnotateIgnoreReadsBegin)()
339 ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE {}
340
341 ABSL_INTERNAL_STATIC_INLINE void ABSL_INTERNAL_C_SYMBOL(
342 AbslInternalAnnotateIgnoreReadsEnd)()
343 ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE {}
344
345 #else
346
347 #define ABSL_ANNOTATE_IGNORE_READS_BEGIN() // empty
348 #define ABSL_ANNOTATE_IGNORE_READS_END() // empty
349
350 #endif
351
352 // -------------------------------------------------------------------------
353 // Define IGNORE_WRITES_BEGIN/_END annotations.
354
355 #if ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED == 1
356
357 // Similar to ABSL_ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead.
358 #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() \
359 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesBegin)(__FILE__, __LINE__)
360
361 // Stop ignoring writes.
362 #define ABSL_ANNOTATE_IGNORE_WRITES_END() \
363 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesEnd)(__FILE__, __LINE__)
364
365 // Function prototypes of annotations provided by the compiler-based sanitizer
366 // implementation.
367 ABSL_INTERNAL_BEGIN_EXTERN_C
368 void AnnotateIgnoreWritesBegin(const char* file, int line);
369 void AnnotateIgnoreWritesEnd(const char* file, int line);
370 ABSL_INTERNAL_END_EXTERN_C
371
372 #else
373
374 #define ABSL_ANNOTATE_IGNORE_WRITES_BEGIN() // empty
375 #define ABSL_ANNOTATE_IGNORE_WRITES_END() // empty
376
377 #endif
378
379 // -------------------------------------------------------------------------
380 // Define the ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more
381 // primitive annotations defined above.
382 //
383 // Instead of doing
384 // ABSL_ANNOTATE_IGNORE_READS_BEGIN();
385 // ... = x;
386 // ABSL_ANNOTATE_IGNORE_READS_END();
387 // one can use
388 // ... = ABSL_ANNOTATE_UNPROTECTED_READ(x);
389
390 #if defined(ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED)
391
392 // Start ignoring all memory accesses (both reads and writes).
393 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
394 do { \
395 ABSL_ANNOTATE_IGNORE_READS_BEGIN(); \
396 ABSL_ANNOTATE_IGNORE_WRITES_BEGIN(); \
397 } while (0)
398
399 // Stop ignoring both reads and writes.
400 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() \
401 do { \
402 ABSL_ANNOTATE_IGNORE_WRITES_END(); \
403 ABSL_ANNOTATE_IGNORE_READS_END(); \
404 } while (0)
405
406 #ifdef __cplusplus
407 // ABSL_ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads.
408 #define ABSL_ANNOTATE_UNPROTECTED_READ(x) \
409 absl::base_internal::AnnotateUnprotectedRead(x)
410
411 namespace absl {
412 ABSL_NAMESPACE_BEGIN
413 namespace base_internal {
414
415 template <typename T>
AnnotateUnprotectedRead(const volatile T & x)416 inline T AnnotateUnprotectedRead(const volatile T& x) { // NOLINT
417 ABSL_ANNOTATE_IGNORE_READS_BEGIN();
418 T res = x;
419 ABSL_ANNOTATE_IGNORE_READS_END();
420 return res;
421 }
422
423 } // namespace base_internal
424 ABSL_NAMESPACE_END
425 } // namespace absl
426 #endif
427
428 #else
429
430 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() // empty
431 #define ABSL_ANNOTATE_IGNORE_READS_AND_WRITES_END() // empty
432 #define ABSL_ANNOTATE_UNPROTECTED_READ(x) (x)
433
434 #endif
435
436 // -------------------------------------------------------------------------
437 // Address sanitizer annotations
438
439 #ifdef ABSL_HAVE_ADDRESS_SANITIZER
440 // Describe the current state of a contiguous container such as e.g.
441 // std::vector or std::string. For more details see
442 // sanitizer/common_interface_defs.h, which is provided by the compiler.
443 #include <sanitizer/common_interface_defs.h>
444
445 #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) \
446 __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid)
447 #define ABSL_ADDRESS_SANITIZER_REDZONE(name) \
448 struct { \
449 alignas(8) char x[8]; \
450 } name
451
452 #else
453
454 #define ABSL_ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) // empty
455 #define ABSL_ADDRESS_SANITIZER_REDZONE(name) static_assert(true, "")
456
457 #endif // ABSL_HAVE_ADDRESS_SANITIZER
458
459 // -------------------------------------------------------------------------
460 // Undefine the macros intended only for this file.
461
462 #undef ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED
463 #undef ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED
464 #undef ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED
465 #undef ABSL_INTERNAL_ANNOTALYSIS_ENABLED
466 #undef ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED
467 #undef ABSL_INTERNAL_BEGIN_EXTERN_C
468 #undef ABSL_INTERNAL_END_EXTERN_C
469 #undef ABSL_INTERNAL_STATIC_INLINE
470
471 #endif // ABSL_BASE_DYNAMIC_ANNOTATIONS_H_
472