base/thread_annotations.h

   1 // Copyright (c) 2018 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This header file contains macro definitions for thread safety annotations
   6 // that allow developers to document the locking policies of multi-threaded
   7 // code. The annotations can also help program analysis tools to identify
   8 // potential thread safety issues.
   9 //
  10 // Note that the annotations we use are described as deprecated in the Clang
  11 // documentation, linked below. E.g. we use EXCLUSIVE_LOCKS_REQUIRED where the
  12 // Clang docs use REQUIRES.
  13 //
  14 // http://clang.llvm.org/docs/ThreadSafetyAnalysis.html
  15 //
  16 // We use the deprecated Clang annotations to match Abseil (relevant header
  17 // linked below) and its ecosystem of libraries. We will follow Abseil with
  18 // respect to upgrading to more modern annotations.
  19 //
  20 // https://github.com/abseil/abseil-cpp/blob/master/absl/base/thread_annotations.h
  21 //
  22 // These annotations are implemented using compiler attributes. Using the macros
  23 // defined here instead of raw attributes allow for portability and future
  24 // compatibility.
  25 //
  26 // When referring to mutexes in the arguments of the attributes, you should
  27 // use variable names or more complex expressions (e.g. my_object->mutex_)
  28 // that evaluate to a concrete mutex object whenever possible. If the mutex
  29 // you want to refer to is not in scope, you may use a member pointer
  30 // (e.g. &MyClass::mutex_) to refer to a mutex in some (unknown) object.
  31
  32 #ifndef THREAD_ANNOTATIONS_H_
  33 #define THREAD_ANNOTATIONS_H_
  34
  35 #if defined(__clang__)
  36 #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
  37 #else
  38 #define THREAD_ANNOTATION_ATTRIBUTE__(x)  // no-op
  39 #endif
  40
  41 // GUARDED_BY()
  42 //
  43 // Documents if a shared field or global variable needs to be protected by a
  44 // mutex. GUARDED_BY() allows the user to specify a particular mutex that
  45 // should be held when accessing the annotated variable.
  46 //
  47 // Example:
  48 //
  49 //   Mutex mu;
  50 //   int p1 GUARDED_BY(mu);
  51 #define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
  52
  53 // PT_GUARDED_BY()
  54 //
  55 // Documents if the memory location pointed to by a pointer should be guarded
  56 // by a mutex when dereferencing the pointer.
  57 //
  58 // Example:
  59 //   Mutex mu;
  60 //   int *p1 PT_GUARDED_BY(mu);
  61 //
  62 // Note that a pointer variable to a shared memory location could itself be a
  63 // shared variable.
  64 //
  65 // Example:
  66 //
  67 //     // `q`, guarded by `mu1`, points to a shared memory location that is
  68 //     // guarded by `mu2`:
  69 //     int *q GUARDED_BY(mu1) PT_GUARDED_BY(mu2);
  70 #define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
  71
  72 // ACQUIRED_AFTER() / ACQUIRED_BEFORE()
  73 //
  74 // Documents the acquisition order between locks that can be held
  75 // simultaneously by a thread. For any two locks that need to be annotated
  76 // to establish an acquisition order, only one of them needs the annotation.
  77 // (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
  78 // and ACQUIRED_BEFORE.)
  79 //
  80 // Example:
  81 //
  82 //   Mutex m1;
  83 //   Mutex m2 ACQUIRED_AFTER(m1);
  84 #define ACQUIRED_AFTER(...) \
  85   THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
  86
  87 #define ACQUIRED_BEFORE(...) \
  88   THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
  89
  90 // EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED()
  91 //
  92 // Documents a function that expects a mutex to be held prior to entry.
  93 // The mutex is expected to be held both on entry to, and exit from, the
  94 // function.
  95 //
  96 // Example:
  97 //
  98 //   Mutex mu1, mu2;
  99 //   int a GUARDED_BY(mu1);
 100 //   int b GUARDED_BY(mu2);
 101 //
 102 //   void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... };
 103 #define EXCLUSIVE_LOCKS_REQUIRED(...) \
 104   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
 105
 106 #define SHARED_LOCKS_REQUIRED(...) \
 107   THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
 108
 109 // LOCKS_EXCLUDED()
 110 //
 111 // Documents the locks acquired in the body of the function. These locks
 112 // cannot be held when calling this function (as Abseil's `Mutex` locks are
 113 // non-reentrant).
 114 #define LOCKS_EXCLUDED(...) \
 115   THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
 116
 117 // LOCK_RETURNED()
 118 //
 119 // Documents a function that returns a mutex without acquiring it.  For example,
 120 // a public getter method that returns a pointer to a private mutex should
 121 // be annotated with LOCK_RETURNED.
 122 #define LOCK_RETURNED(x) THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
 123
 124 // LOCKABLE
 125 //
 126 // Documents if a class/type is a lockable type (such as the `Mutex` class).
 127 #define LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(lockable)
 128
 129 // SCOPED_LOCKABLE
 130 //
 131 // Documents if a class does RAII locking (such as the `MutexLock` class).
 132 // The constructor should use `LOCK_FUNCTION()` to specify the mutex that is
 133 // acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
 134 // arguments; the analysis will assume that the destructor unlocks whatever the
 135 // constructor locked.
 136 #define SCOPED_LOCKABLE THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
 137
 138 // EXCLUSIVE_LOCK_FUNCTION()
 139 //
 140 // Documents functions that acquire a lock in the body of a function, and do
 141 // not release it.
 142 #define EXCLUSIVE_LOCK_FUNCTION(...) \
 143   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
 144
 145 // SHARED_LOCK_FUNCTION()
 146 //
 147 // Documents functions that acquire a shared (reader) lock in the body of a
 148 // function, and do not release it.
 149 #define SHARED_LOCK_FUNCTION(...) \
 150   THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
 151
 152 // UNLOCK_FUNCTION()
 153 //
 154 // Documents functions that expect a lock to be held on entry to the function,
 155 // and release it in the body of the function.
 156 #define UNLOCK_FUNCTION(...) \
 157   THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
 158
 159 // EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION()
 160 //
 161 // Documents functions that try to acquire a lock, and return success or failure
 162 // (or a non-boolean value that can be interpreted as a boolean).
 163 // The first argument should be `true` for functions that return `true` on
 164 // success, or `false` for functions that return `false` on success. The second
 165 // argument specifies the mutex that is locked on success. If unspecified, this
 166 // mutex is assumed to be `this`.
 167 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
 168   THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
 169
 170 #define SHARED_TRYLOCK_FUNCTION(...) \
 171   THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
 172
 173 // ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK()
 174 //
 175 // Documents functions that dynamically check to see if a lock is held, and fail
 176 // if it is not held.
 177 #define ASSERT_EXCLUSIVE_LOCK(...) \
 178   THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
 179
 180 #define ASSERT_SHARED_LOCK(...) \
 181   THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
 182
 183 // NO_THREAD_SAFETY_ANALYSIS
 184 //
 185 // Turns off thread safety checking within the body of a particular function.
 186 // This annotation is used to mark functions that are known to be correct, but
 187 // the locking behavior is more complicated than the analyzer can handle.
 188 #define NO_THREAD_SAFETY_ANALYSIS \
 189   THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 190
 191 //------------------------------------------------------------------------------
 192 // Tool-Supplied Annotations
 193 //------------------------------------------------------------------------------
 194
 195 // TS_UNCHECKED should be placed around lock expressions that are not valid
 196 // C++ syntax, but which are present for documentation purposes.  These
 197 // annotations will be ignored by the analysis.
 198 #define TS_UNCHECKED(x) ""
 199
 200 // TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
 201 // It is used by automated tools to mark and disable invalid expressions.
 202 // The annotation should either be fixed, or changed to TS_UNCHECKED.
 203 #define TS_FIXME(x) ""
 204
 205 // Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of
 206 // a particular function.  However, this attribute is used to mark functions
 207 // that are incorrect and need to be fixed.  It is used by automated tools to
 208 // avoid breaking the build when the analysis is updated.
 209 // Code owners are expected to eventually fix the routine.
 210 #define NO_THREAD_SAFETY_ANALYSIS_FIXME NO_THREAD_SAFETY_ANALYSIS
 211
 212 // Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY
 213 // annotation that needs to be fixed, because it is producing thread safety
 214 // warning.  It disables the GUARDED_BY.
 215 #define GUARDED_BY_FIXME(x)
 216
 217 // Disables warnings for a single read operation.  This can be used to avoid
 218 // warnings when it is known that the read is not actually involved in a race,
 219 // but the compiler cannot confirm that.
 220 #define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x)
 221
 222 namespace thread_safety_analysis {
 223
 224 // Takes a reference to a guarded data member, and returns an unguarded
 225 // reference.
 226 template <typename T>
 227 inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS {
 228   return v;
 229 }
 230
 231 template <typename T>
 232 inline T& ts_unchecked_read(T& v) NO_THREAD_SAFETY_ANALYSIS {
 233   return v;
 234 }
 235
 236 }  // namespace thread_safety_analysis
 237
 238 #endif  // _BASE_THREAD_ANNOTATIONS_H_