1// Copyright 2019 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// -----------------------------------------------------------------------------
16// File: thread_annotations.h
17// -----------------------------------------------------------------------------
18//
19// WARNING: This is a backwards compatible header and it will be removed after
20// the migration to prefixed thread annotations is finished; please include
21// "absl/base/thread_annotations.h".
22//
23// This header file contains macro definitions for thread safety annotations
24// that allow developers to document the locking policies of multi-threaded
25// code. The annotations can also help program analysis tools to identify
26// potential thread safety issues.
27//
28// These annotations are implemented using compiler attributes. Using the macros
29// defined here instead of raw attributes allow for portability and future
30// compatibility.
31//
32// When referring to mutexes in the arguments of the attributes, you should
33// use variable names or more complex expressions (e.g. my_object->mutex_)
34// that evaluate to a concrete mutex object whenever possible. If the mutex
35// you want to refer to is not in scope, you may use a member pointer
36// (e.g. &MyClass::mutex_) to refer to a mutex in some (unknown) object.
37
38#ifndef ABSL_BASE_INTERNAL_THREAD_ANNOTATIONS_H_
39#define ABSL_BASE_INTERNAL_THREAD_ANNOTATIONS_H_
40
41#if defined(__clang__)
42#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
43#else
44#define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
45#endif
46
47// GUARDED_BY()
48//
49// Documents if a shared field or global variable needs to be protected by a
50// mutex. GUARDED_BY() allows the user to specify a particular mutex that
51// should be held when accessing the annotated variable.
52//
53// Although this annotation (and PT_GUARDED_BY, below) cannot be applied to
54// local variables, a local variable and its associated mutex can often be
55// combined into a small class or struct, thereby allowing the annotation.
56//
57// Example:
58//
59// class Foo {
60// Mutex mu_;
61// int p1_ GUARDED_BY(mu_);
62// ...
63// };
64#define GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
65
66// PT_GUARDED_BY()
67//
68// Documents if the memory location pointed to by a pointer should be guarded
69// by a mutex when dereferencing the pointer.
70//
71// Example:
72// class Foo {
73// Mutex mu_;
74// int *p1_ PT_GUARDED_BY(mu_);
75// ...
76// };
77//
78// Note that a pointer variable to a shared memory location could itself be a
79// shared variable.
80//
81// Example:
82//
83// // `q_`, guarded by `mu1_`, points to a shared memory location that is
84// // guarded by `mu2_`:
85// int *q_ GUARDED_BY(mu1_) PT_GUARDED_BY(mu2_);
86#define PT_GUARDED_BY(x) THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
87
88// ACQUIRED_AFTER() / ACQUIRED_BEFORE()
89//
90// Documents the acquisition order between locks that can be held
91// simultaneously by a thread. For any two locks that need to be annotated
92// to establish an acquisition order, only one of them needs the annotation.
93// (i.e. You don't have to annotate both locks with both ACQUIRED_AFTER
94// and ACQUIRED_BEFORE.)
95//
96// As with GUARDED_BY, this is only applicable to mutexes that are shared
97// fields or global variables.
98//
99// Example:
100//
101// Mutex m1_;
102// Mutex m2_ ACQUIRED_AFTER(m1_);
103#define ACQUIRED_AFTER(...) \
104 THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
105
106#define ACQUIRED_BEFORE(...) \
107 THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
108
109// EXCLUSIVE_LOCKS_REQUIRED() / SHARED_LOCKS_REQUIRED()
110//
111// Documents a function that expects a mutex to be held prior to entry.
112// The mutex is expected to be held both on entry to, and exit from, the
113// function.
114//
115// An exclusive lock allows read-write access to the guarded data member(s), and
116// only one thread can acquire a lock exclusively at any one time. A shared lock
117// allows read-only access, and any number of threads can acquire a shared lock
118// concurrently.
119//
120// Generally, non-const methods should be annotated with
121// EXCLUSIVE_LOCKS_REQUIRED, while const methods should be annotated with
122// SHARED_LOCKS_REQUIRED.
123//
124// Example:
125//
126// Mutex mu1, mu2;
127// int a GUARDED_BY(mu1);
128// int b GUARDED_BY(mu2);
129//
130// void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) { ... }
131// void bar() const SHARED_LOCKS_REQUIRED(mu1, mu2) { ... }
132#define EXCLUSIVE_LOCKS_REQUIRED(...) \
133 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
134
135#define SHARED_LOCKS_REQUIRED(...) \
136 THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
137
138// LOCKS_EXCLUDED()
139//
140// Documents the locks acquired in the body of the function. These locks
141// cannot be held when calling this function (as Abseil's `Mutex` locks are
142// non-reentrant).
143#define LOCKS_EXCLUDED(...) \
144 THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
145
146// LOCK_RETURNED()
147//
148// Documents a function that returns a mutex without acquiring it. For example,
149// a public getter method that returns a pointer to a private mutex should
150// be annotated with LOCK_RETURNED.
151#define LOCK_RETURNED(x) \
152 THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
153
154// LOCKABLE
155//
156// Documents if a class/type is a lockable type (such as the `Mutex` class).
157#define LOCKABLE \
158 THREAD_ANNOTATION_ATTRIBUTE__(lockable)
159
160// SCOPED_LOCKABLE
161//
162// Documents if a class does RAII locking (such as the `MutexLock` class).
163// The constructor should use `LOCK_FUNCTION()` to specify the mutex that is
164// acquired, and the destructor should use `UNLOCK_FUNCTION()` with no
165// arguments; the analysis will assume that the destructor unlocks whatever the
166// constructor locked.
167#define SCOPED_LOCKABLE \
168 THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
169
170// EXCLUSIVE_LOCK_FUNCTION()
171//
172// Documents functions that acquire a lock in the body of a function, and do
173// not release it.
174#define EXCLUSIVE_LOCK_FUNCTION(...) \
175 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
176
177// SHARED_LOCK_FUNCTION()
178//
179// Documents functions that acquire a shared (reader) lock in the body of a
180// function, and do not release it.
181#define SHARED_LOCK_FUNCTION(...) \
182 THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
183
184// UNLOCK_FUNCTION()
185//
186// Documents functions that expect a lock to be held on entry to the function,
187// and release it in the body of the function.
188#define UNLOCK_FUNCTION(...) \
189 THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
190
191// EXCLUSIVE_TRYLOCK_FUNCTION() / SHARED_TRYLOCK_FUNCTION()
192//
193// Documents functions that try to acquire a lock, and return success or failure
194// (or a non-boolean value that can be interpreted as a boolean).
195// The first argument should be `true` for functions that return `true` on
196// success, or `false` for functions that return `false` on success. The second
197// argument specifies the mutex that is locked on success. If unspecified, this
198// mutex is assumed to be `this`.
199#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
200 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
201
202#define SHARED_TRYLOCK_FUNCTION(...) \
203 THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
204
205// ASSERT_EXCLUSIVE_LOCK() / ASSERT_SHARED_LOCK()
206//
207// Documents functions that dynamically check to see if a lock is held, and fail
208// if it is not held.
209#define ASSERT_EXCLUSIVE_LOCK(...) \
210 THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
211
212#define ASSERT_SHARED_LOCK(...) \
213 THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
214
215// NO_THREAD_SAFETY_ANALYSIS
216//
217// Turns off thread safety checking within the body of a particular function.
218// This annotation is used to mark functions that are known to be correct, but
219// the locking behavior is more complicated than the analyzer can handle.
220#define NO_THREAD_SAFETY_ANALYSIS \
221 THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
222
223//------------------------------------------------------------------------------
224// Tool-Supplied Annotations
225//------------------------------------------------------------------------------
226
227// TS_UNCHECKED should be placed around lock expressions that are not valid
228// C++ syntax, but which are present for documentation purposes. These
229// annotations will be ignored by the analysis.
230#define TS_UNCHECKED(x) ""
231
232// TS_FIXME is used to mark lock expressions that are not valid C++ syntax.
233// It is used by automated tools to mark and disable invalid expressions.
234// The annotation should either be fixed, or changed to TS_UNCHECKED.
235#define TS_FIXME(x) ""
236
237// Like NO_THREAD_SAFETY_ANALYSIS, this turns off checking within the body of
238// a particular function. However, this attribute is used to mark functions
239// that are incorrect and need to be fixed. It is used by automated tools to
240// avoid breaking the build when the analysis is updated.
241// Code owners are expected to eventually fix the routine.
242#define NO_THREAD_SAFETY_ANALYSIS_FIXME NO_THREAD_SAFETY_ANALYSIS
243
244// Similar to NO_THREAD_SAFETY_ANALYSIS_FIXME, this macro marks a GUARDED_BY
245// annotation that needs to be fixed, because it is producing thread safety
246// warning. It disables the GUARDED_BY.
247#define GUARDED_BY_FIXME(x)
248
249// Disables warnings for a single read operation. This can be used to avoid
250// warnings when it is known that the read is not actually involved in a race,
251// but the compiler cannot confirm that.
252#define TS_UNCHECKED_READ(x) thread_safety_analysis::ts_unchecked_read(x)
253
254
255namespace thread_safety_analysis {
256
257// Takes a reference to a guarded data member, and returns an unguarded
258// reference.
259template <typename T>
260inline const T& ts_unchecked_read(const T& v) NO_THREAD_SAFETY_ANALYSIS {
261 return v;
262}
263
264template <typename T>
265inline T& ts_unchecked_read(T& v) NO_THREAD_SAFETY_ANALYSIS {
266 return v;
267}
268
269} // namespace thread_safety_analysis
270
271#endif // ABSL_BASE_INTERNAL_THREAD_ANNOTATIONS_H_
272