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