andresp@webrtc.org | 7fb75ec | 2013-12-20 20:20:50 +0000 | [diff] [blame] | 1 | // |
| 2 | // Copyright (c) 2013 The WebRTC project authors. All Rights Reserved. |
| 3 | // |
| 4 | // Use of this source code is governed by a BSD-style license |
| 5 | // that can be found in the LICENSE file in the root of the source |
| 6 | // tree. An additional intellectual property rights grant can be found |
| 7 | // in the file PATENTS. All contributing project authors may |
| 8 | // be found in the AUTHORS file in the root of the source tree. |
| 9 | // |
| 10 | // Borrowed from |
| 11 | // https://code.google.com/p/gperftools/source/browse/src/base/thread_annotations.h |
| 12 | // but adapted for clang attributes instead of the gcc. |
| 13 | // |
| 14 | // This header file contains the macro definitions for thread safety |
| 15 | // annotations that allow the developers to document the locking policies |
| 16 | // of their multi-threaded code. The annotations can also help program |
| 17 | // analysis tools to identify potential thread safety issues. |
| 18 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 19 | #ifndef RTC_BASE_THREAD_ANNOTATIONS_H_ |
| 20 | #define RTC_BASE_THREAD_ANNOTATIONS_H_ |
andresp@webrtc.org | 7fb75ec | 2013-12-20 20:20:50 +0000 | [diff] [blame] | 21 | |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 22 | #if defined(__clang__) && (!defined(SWIG)) |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 23 | #define RTC_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 24 | #else |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 25 | #define RTC_THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 26 | #endif |
andresp@webrtc.org | 7fb75ec | 2013-12-20 20:20:50 +0000 | [diff] [blame] | 27 | |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 28 | // Document if a shared variable/field needs to be protected by a lock. |
| 29 | // GUARDED_BY allows the user to specify a particular lock that should be |
Danil Chapovalov | 3765199 | 2017-11-01 10:52:09 +0100 | [diff] [blame] | 30 | // held when accessing the annotated variable. |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 31 | #define RTC_GUARDED_BY(x) RTC_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 32 | |
| 33 | // Document if the memory location pointed to by a pointer should be guarded |
Danil Chapovalov | 3765199 | 2017-11-01 10:52:09 +0100 | [diff] [blame] | 34 | // by a lock when dereferencing the pointer. Note that a pointer variable to a |
| 35 | // shared memory location could itself be a shared variable. For example, if a |
| 36 | // shared global pointer q, which is guarded by mu1, points to a shared memory |
| 37 | // location that is guarded by mu2, q should be annotated as follows: |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 38 | // int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2); |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 39 | #define RTC_PT_GUARDED_BY(x) RTC_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 40 | |
| 41 | // Document the acquisition order between locks that can be held |
| 42 | // simultaneously by a thread. For any two locks that need to be annotated |
| 43 | // to establish an acquisition order, only one of them needs the annotation. |
| 44 | // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER |
| 45 | // and ACQUIRED_BEFORE.) |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 46 | #define RTC_ACQUIRED_AFTER(x) \ |
| 47 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 48 | #define RTC_ACQUIRED_BEFORE(x) \ |
| 49 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 50 | |
| 51 | // The following three annotations document the lock requirements for |
| 52 | // functions/methods. |
| 53 | |
| 54 | // Document if a function expects certain locks to be held before it is called |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 55 | #define RTC_EXCLUSIVE_LOCKS_REQUIRED(...) \ |
| 56 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__)) |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 57 | #define RTC_SHARED_LOCKS_REQUIRED(...) \ |
| 58 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 59 | |
| 60 | // Document the locks acquired in the body of the function. These locks |
| 61 | // cannot be held when calling this function (as google3's Mutex locks are |
| 62 | // non-reentrant). |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 63 | #define RTC_LOCKS_EXCLUDED(...) \ |
| 64 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 65 | |
| 66 | // Document the lock the annotated function returns without acquiring it. |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 67 | #define RTC_LOCK_RETURNED(x) RTC_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 68 | |
| 69 | // Document if a class/type is a lockable type (such as the Mutex class). |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 70 | #define RTC_LOCKABLE RTC_THREAD_ANNOTATION_ATTRIBUTE__(lockable) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 71 | |
| 72 | // Document if a class is a scoped lockable type (such as the MutexLock class). |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 73 | #define RTC_SCOPED_LOCKABLE RTC_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 74 | |
| 75 | // The following annotations specify lock and unlock primitives. |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 76 | #define RTC_EXCLUSIVE_LOCK_FUNCTION(...) \ |
| 77 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 78 | |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 79 | #define RTC_SHARED_LOCK_FUNCTION(...) \ |
| 80 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 81 | |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 82 | #define RTC_EXCLUSIVE_TRYLOCK_FUNCTION(...) \ |
| 83 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 84 | |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 85 | #define RTC_SHARED_TRYLOCK_FUNCTION(...) \ |
| 86 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 87 | |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 88 | #define RTC_UNLOCK_FUNCTION(...) \ |
| 89 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__)) |
Henrik Kjellander | ec78f1c | 2017-06-29 07:52:50 +0200 | [diff] [blame] | 90 | |
| 91 | // An escape hatch for thread safety analysis to ignore the annotated function. |
danilchap | 5301e3c | 2017-09-06 04:10:21 -0700 | [diff] [blame] | 92 | #define RTC_NO_THREAD_SAFETY_ANALYSIS \ |
| 93 | RTC_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) |
andresp@webrtc.org | 7fb75ec | 2013-12-20 20:20:50 +0000 | [diff] [blame] | 94 | |
Mirko Bonadei | 92ea95e | 2017-09-15 06:47:31 +0200 | [diff] [blame] | 95 | #endif // RTC_BASE_THREAD_ANNOTATIONS_H_ |