1 /*
2 * Copyright 2017 The Abseil Authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 /* This file defines dynamic annotations for use with dynamic analysis
17 tool such as valgrind, PIN, etc.
18
19 Dynamic annotation is a source code annotation that affects
20 the generated code (that is, the annotation is not a comment).
21 Each such annotation is attached to a particular
22 instruction and/or to a particular object (address) in the program.
23
24 The annotations that should be used by users are macros in all upper-case
25 (e.g., ANNOTATE_THREAD_NAME).
26
27 Actual implementation of these macros may differ depending on the
28 dynamic analysis tool being used.
29
30 This file supports the following configurations:
31 - Dynamic Annotations enabled (with static thread-safety warnings disabled).
32 In this case, macros expand to functions implemented by Thread Sanitizer,
33 when building with TSan. When not provided an external implementation,
34 dynamic_annotations.cc provides no-op implementations.
35
36 - Static Clang thread-safety warnings enabled.
37 When building with a Clang compiler that supports thread-safety warnings,
38 a subset of annotations can be statically-checked at compile-time. We
39 expand these macros to static-inline functions that can be analyzed for
40 thread-safety, but afterwards elided when building the final binary.
41
42 - All annotations are disabled.
43 If neither Dynamic Annotations nor Clang thread-safety warnings are
44 enabled, then all annotation-macros expand to empty. */
45
46 #ifndef S2_THIRD_PARTY_ABSL_BASE_DYNAMIC_ANNOTATIONS_H_
47 #define S2_THIRD_PARTY_ABSL_BASE_DYNAMIC_ANNOTATIONS_H_
48
49 #ifndef DYNAMIC_ANNOTATIONS_ENABLED
50 # define DYNAMIC_ANNOTATIONS_ENABLED 0
51 #endif
52
53 #if DYNAMIC_ANNOTATIONS_ENABLED != 0
54
55 /* -------------------------------------------------------------
56 Annotations that suppress errors. It is usually better to express the
57 program's synchronization using the other annotations, but these can
58 be used when all else fails. */
59
60 /* Report that we may have a benign race at "pointer", with size
61 "sizeof(*(pointer))". "pointer" must be a non-void* pointer. Insert at the
62 point where "pointer" has been allocated, preferably close to the point
63 where the race happens. See also ANNOTATE_BENIGN_RACE_STATIC. */
64 #define ANNOTATE_BENIGN_RACE(pointer, description) \
65 AnnotateBenignRaceSized(__FILE__, __LINE__, pointer, \
66 sizeof(*(pointer)), description)
67
68 /* Same as ANNOTATE_BENIGN_RACE(address, description), but applies to
69 the memory range [address, address+size). */
70 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \
71 AnnotateBenignRaceSized(__FILE__, __LINE__, address, size, description)
72
73 /* Enable (enable!=0) or disable (enable==0) race detection for all threads.
74 This annotation could be useful if you want to skip expensive race analysis
75 during some period of program execution, e.g. during initialization. */
76 #define ANNOTATE_ENABLE_RACE_DETECTION(enable) \
77 AnnotateEnableRaceDetection(__FILE__, __LINE__, enable)
78
79 /* -------------------------------------------------------------
80 Annotations useful for debugging. */
81
82 /* Report the current thread name to a race detector. */
83 #define ANNOTATE_THREAD_NAME(name) \
84 AnnotateThreadName(__FILE__, __LINE__, name)
85
86 /* -------------------------------------------------------------
87 Annotations useful when implementing locks. They are not
88 normally needed by modules that merely use locks.
89 The "lock" argument is a pointer to the lock object. */
90
91 /* Report that a lock has been created at address "lock". */
92 #define ANNOTATE_RWLOCK_CREATE(lock) \
93 AnnotateRWLockCreate(__FILE__, __LINE__, lock)
94
95 /* Report that a linker initialized lock has been created at address "lock".
96 */
97 #ifdef THREAD_SANITIZER
98 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) \
99 AnnotateRWLockCreateStatic(__FILE__, __LINE__, lock)
100 #else
101 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) ANNOTATE_RWLOCK_CREATE(lock)
102 #endif
103
104 /* Report that the lock at address "lock" is about to be destroyed. */
105 #define ANNOTATE_RWLOCK_DESTROY(lock) \
106 AnnotateRWLockDestroy(__FILE__, __LINE__, lock)
107
108 /* Report that the lock at address "lock" has been acquired.
109 is_w=1 for writer lock, is_w=0 for reader lock. */
110 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \
111 AnnotateRWLockAcquired(__FILE__, __LINE__, lock, is_w)
112
113 /* Report that the lock at address "lock" is about to be released. */
114 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \
115 AnnotateRWLockReleased(__FILE__, __LINE__, lock, is_w)
116
117 #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
118
119 #define ANNOTATE_RWLOCK_CREATE(lock) /* empty */
120 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) /* empty */
121 #define ANNOTATE_RWLOCK_DESTROY(lock) /* empty */
122 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) /* empty */
123 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) /* empty */
124 #define ANNOTATE_BENIGN_RACE(address, description) /* empty */
125 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) /* empty */
126 #define ANNOTATE_THREAD_NAME(name) /* empty */
127 #define ANNOTATE_ENABLE_RACE_DETECTION(enable) /* empty */
128
129 #endif /* DYNAMIC_ANNOTATIONS_ENABLED */
130
131 /* These annotations are also made available to LLVM's Memory Sanitizer */
132 #if DYNAMIC_ANNOTATIONS_ENABLED == 1 || defined(MEMORY_SANITIZER)
133 #define ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \
134 AnnotateMemoryIsInitialized(__FILE__, __LINE__, address, size)
135
136 #define ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \
137 AnnotateMemoryIsUninitialized(__FILE__, __LINE__, address, size)
138 #else
139 #define ANNOTATE_MEMORY_IS_INITIALIZED(address, size) /* empty */
140 #define ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) /* empty */
141 #endif /* DYNAMIC_ANNOTATIONS_ENABLED || MEMORY_SANITIZER */
142
143 #ifdef SWIG
144 #define ATTRIBUTE_IGNORE_READS_BEGIN /* empty */
145 #define ATTRIBUTE_IGNORE_READS_END /* empty */
146 #else // SWIG
147 /* TODO(user) -- Replace __CLANG_SUPPORT_DYN_ANNOTATION__ with the
148 appropriate feature ID. */
149 #if defined(__clang__) && (!defined(SWIG)) \
150 && defined(__CLANG_SUPPORT_DYN_ANNOTATION__)
151
152 #if DYNAMIC_ANNOTATIONS_ENABLED == 0
153 #define ANNOTALYSIS_ENABLED
154 #endif
155
156 /* When running in opt-mode, GCC will issue a warning, if these attributes are
157 compiled. Only include them when compiling using Clang. */
158 #define ATTRIBUTE_IGNORE_READS_BEGIN \
159 __attribute((exclusive_lock_function("*")))
160 #define ATTRIBUTE_IGNORE_READS_END \
161 __attribute((unlock_function("*")))
162 #else
163 #define ATTRIBUTE_IGNORE_READS_BEGIN /* empty */
164 #define ATTRIBUTE_IGNORE_READS_END /* empty */
165 #endif /* defined(__clang__) && ... */
166 #endif
167
168 #if (DYNAMIC_ANNOTATIONS_ENABLED != 0) || defined(ANNOTALYSIS_ENABLED)
169 #define ANNOTATIONS_ENABLED
170 #endif
171
172 #if (DYNAMIC_ANNOTATIONS_ENABLED != 0)
173
174 /* Request the analysis tool to ignore all reads in the current thread
175 until ANNOTATE_IGNORE_READS_END is called.
176 Useful to ignore intentional racey reads, while still checking
177 other reads and all writes.
178 See also ANNOTATE_UNPROTECTED_READ. */
179 #define ANNOTATE_IGNORE_READS_BEGIN() \
180 AnnotateIgnoreReadsBegin(__FILE__, __LINE__)
181
182 /* Stop ignoring reads. */
183 #define ANNOTATE_IGNORE_READS_END() \
184 AnnotateIgnoreReadsEnd(__FILE__, __LINE__)
185
186 /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead. */
187 #define ANNOTATE_IGNORE_WRITES_BEGIN() \
188 AnnotateIgnoreWritesBegin(__FILE__, __LINE__)
189
190 /* Stop ignoring writes. */
191 #define ANNOTATE_IGNORE_WRITES_END() \
192 AnnotateIgnoreWritesEnd(__FILE__, __LINE__)
193
194 /* Clang provides limited support for static thread-safety analysis
195 through a feature called Annotalysis. We configure macro-definitions
196 according to whether Annotalysis support is available. */
197 #elif defined(ANNOTALYSIS_ENABLED)
198
199 #define ANNOTATE_IGNORE_READS_BEGIN() \
200 StaticAnnotateIgnoreReadsBegin(__FILE__, __LINE__)
201
202 #define ANNOTATE_IGNORE_READS_END() \
203 StaticAnnotateIgnoreReadsEnd(__FILE__, __LINE__)
204
205 #define ANNOTATE_IGNORE_WRITES_BEGIN() \
206 StaticAnnotateIgnoreWritesBegin(__FILE__, __LINE__)
207
208 #define ANNOTATE_IGNORE_WRITES_END() \
209 StaticAnnotateIgnoreWritesEnd(__FILE__, __LINE__)
210
211 #else
212 #define ANNOTATE_IGNORE_READS_BEGIN() /* empty */
213 #define ANNOTATE_IGNORE_READS_END() /* empty */
214 #define ANNOTATE_IGNORE_WRITES_BEGIN() /* empty */
215 #define ANNOTATE_IGNORE_WRITES_END() /* empty */
216 #endif
217
218 /* Implement the ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more
219 primitive annotations defined above. */
220 #if defined(ANNOTATIONS_ENABLED)
221
222 /* Start ignoring all memory accesses (both reads and writes). */
223 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
224 do { \
225 ANNOTATE_IGNORE_READS_BEGIN(); \
226 ANNOTATE_IGNORE_WRITES_BEGIN(); \
227 }while (0)
228
229 /* Stop ignoring both reads and writes. */
230 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \
231 do { \
232 ANNOTATE_IGNORE_WRITES_END(); \
233 ANNOTATE_IGNORE_READS_END(); \
234 }while (0)
235
236 #else
237 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() /* empty */
238 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() /* empty */
239 #endif
240
241 /* Use the macros above rather than using these functions directly. */
242 #include <cstddef>
243 #ifdef __cplusplus
244 extern "C" {
245 #endif
246 void AnnotateRWLockCreate(const char *file, int line,
247 const volatile void *lock);
248 void AnnotateRWLockCreateStatic(const char *file, int line,
249 const volatile void *lock);
250 void AnnotateRWLockDestroy(const char *file, int line,
251 const volatile void *lock);
252 void AnnotateRWLockAcquired(const char *file, int line,
253 const volatile void *lock, long is_w); /* NOLINT */
254 void AnnotateRWLockReleased(const char *file, int line,
255 const volatile void *lock, long is_w); /* NOLINT */
256 void AnnotateBenignRace(const char *file, int line,
257 const volatile void *address,
258 const char *description);
259 void AnnotateBenignRaceSized(const char *file, int line,
260 const volatile void *address,
261 size_t size,
262 const char *description);
263 void AnnotateThreadName(const char *file, int line,
264 const char *name);
265 void AnnotateEnableRaceDetection(const char *file, int line, int enable);
266 void AnnotateMemoryIsInitialized(const char *file, int line,
267 const volatile void *mem, size_t size);
268 void AnnotateMemoryIsUninitialized(const char *file, int line,
269 const volatile void *mem, size_t size);
270
271 /* Annotations expand to these functions, when Dynamic Annotations are enabled.
272 These functions are either implemented as no-op calls, if no Sanitizer is
273 attached, or provided with externally-linked implementations by a library
274 like ThreadSanitizer. */
275 void AnnotateIgnoreReadsBegin(const char *file, int line)
276 ATTRIBUTE_IGNORE_READS_BEGIN;
277 void AnnotateIgnoreReadsEnd(const char *file, int line)
278 ATTRIBUTE_IGNORE_READS_END;
279 void AnnotateIgnoreWritesBegin(const char *file, int line);
280 void AnnotateIgnoreWritesEnd(const char *file, int line);
281
282 #if defined(ANNOTALYSIS_ENABLED)
283 /* When Annotalysis is enabled without Dynamic Annotations, the use of
284 static-inline functions allows the annotations to be read at compile-time,
285 while still letting the compiler elide the functions from the final build.
286
287 TODO(user) -- The exclusive lock here ignores writes as well, but
288 allows IGNORE_READS_AND_WRITES to work properly. */
289 #pragma GCC diagnostic push
290 #pragma GCC diagnostic ignored "-Wunused-function"
StaticAnnotateIgnoreReadsBegin(const char * file,int line)291 static inline void StaticAnnotateIgnoreReadsBegin(const char *file, int line)
292 ATTRIBUTE_IGNORE_READS_BEGIN { (void)file; (void)line; }
StaticAnnotateIgnoreReadsEnd(const char * file,int line)293 static inline void StaticAnnotateIgnoreReadsEnd(const char *file, int line)
294 ATTRIBUTE_IGNORE_READS_END { (void)file; (void)line; }
StaticAnnotateIgnoreWritesBegin(const char * file,int line)295 static inline void StaticAnnotateIgnoreWritesBegin(
296 const char *file, int line) { (void)file; (void)line; }
StaticAnnotateIgnoreWritesEnd(const char * file,int line)297 static inline void StaticAnnotateIgnoreWritesEnd(
298 const char *file, int line) { (void)file; (void)line; }
299 #pragma GCC diagnostic pop
300 #endif
301
302 /* Return non-zero value if running under valgrind.
303
304 If "valgrind.h" is included into dynamic_annotations.cc,
305 the regular valgrind mechanism will be used.
306 See http://valgrind.org/docs/manual/manual-core-adv.html about
307 RUNNING_ON_VALGRIND and other valgrind "client requests".
308 The file "valgrind.h" may be obtained by doing
309 svn co svn://svn.valgrind.org/valgrind/trunk/include
310
311 If for some reason you can't use "valgrind.h" or want to fake valgrind,
312 there are two ways to make this function return non-zero:
313 - Use environment variable: export RUNNING_ON_VALGRIND=1
314 - Make your tool intercept the function RunningOnValgrind() and
315 change its return value.
316 */
317 int RunningOnValgrind(void);
318
319 /* ValgrindSlowdown returns:
320 * 1.0, if (RunningOnValgrind() == 0)
321 * 50.0, if (RunningOnValgrind() != 0 && getenv("VALGRIND_SLOWDOWN") == NULL)
322 * atof(getenv("VALGRIND_SLOWDOWN")) otherwise
323 This function can be used to scale timeout values:
324 EXAMPLE:
325 for (;;) {
326 DoExpensiveBackgroundTask();
327 SleepForSeconds(5 * ValgrindSlowdown());
328 }
329 */
330 double ValgrindSlowdown(void);
331
332 #ifdef __cplusplus
333 }
334 #endif
335
336 /* ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads.
337
338 Instead of doing
339 ANNOTATE_IGNORE_READS_BEGIN();
340 ... = x;
341 ANNOTATE_IGNORE_READS_END();
342 one can use
343 ... = ANNOTATE_UNPROTECTED_READ(x); */
344 #if defined(__cplusplus) && defined(ANNOTATIONS_ENABLED)
345 template <typename T>
ANNOTATE_UNPROTECTED_READ(const volatile T & x)346 inline T ANNOTATE_UNPROTECTED_READ(const volatile T &x) { /* NOLINT */
347 ANNOTATE_IGNORE_READS_BEGIN();
348 T res = x;
349 ANNOTATE_IGNORE_READS_END();
350 return res;
351 }
352 #else
353 #define ANNOTATE_UNPROTECTED_READ(x) (x)
354 #endif
355
356 #if DYNAMIC_ANNOTATIONS_ENABLED != 0 && defined(__cplusplus)
357 /* Apply ANNOTATE_BENIGN_RACE_SIZED to a static variable. */
358 #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \
359 namespace { \
360 class static_var ## _annotator { \
361 public: \
362 static_var ## _annotator() { \
363 ANNOTATE_BENIGN_RACE_SIZED(&static_var, \
364 sizeof(static_var), \
365 # static_var ": " description); \
366 } \
367 }; \
368 static static_var ## _annotator the ## static_var ## _annotator;\
369 } // namespace
370 #else /* DYNAMIC_ANNOTATIONS_ENABLED == 0 */
371 #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description) /* empty */
372 #endif /* DYNAMIC_ANNOTATIONS_ENABLED */
373
374 #ifdef ADDRESS_SANITIZER
375 /* Describe the current state of a contiguous container such as e.g.
376 * std::vector or std::string. For more details see
377 * sanitizer/common_interface_defs.h, which is provided by the compiler. */
378 #include <sanitizer/common_interface_defs.h>
379 #define ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) \
380 __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid)
381 #define ADDRESS_SANITIZER_REDZONE(name) \
382 struct { char x[8] __attribute__ ((aligned (8))); } name
383 #else
384 #define ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid)
385 #define ADDRESS_SANITIZER_REDZONE(name)
386 #endif // ADDRESS_SANITIZER
387
388 /* Undefine the macros intended only in this file. */
389 #undef ANNOTALYSIS_ENABLED
390 #undef ANNOTATIONS_ENABLED
391 #undef ATTRIBUTE_IGNORE_READS_BEGIN
392 #undef ATTRIBUTE_IGNORE_READS_END
393
394 #endif /* THIRD_PARTY_ABSL_BASE_DYNAMIC_ANNOTATIONS_H_ */
395