thread_annotations.h 9.8 KB

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