|
150
|
1
|
|
|
2 ======================
|
|
|
3 Thread Safety Analysis
|
|
|
4 ======================
|
|
|
5
|
|
|
6 Introduction
|
|
|
7 ============
|
|
|
8
|
|
|
9 Clang Thread Safety Analysis is a C++ language extension which warns about
|
|
|
10 potential race conditions in code. The analysis is completely static (i.e.
|
|
|
11 compile-time); there is no run-time overhead. The analysis is still
|
|
|
12 under active development, but it is mature enough to be deployed in an
|
|
|
13 industrial setting. It is being developed by Google, in collaboration with
|
|
|
14 CERT/SEI, and is used extensively in Google's internal code base.
|
|
|
15
|
|
|
16 Thread safety analysis works very much like a type system for multi-threaded
|
|
|
17 programs. In addition to declaring the *type* of data (e.g. ``int``, ``float``,
|
|
|
18 etc.), the programmer can (optionally) declare how access to that data is
|
|
|
19 controlled in a multi-threaded environment. For example, if ``foo`` is
|
|
|
20 *guarded by* the mutex ``mu``, then the analysis will issue a warning whenever
|
|
|
21 a piece of code reads or writes to ``foo`` without first locking ``mu``.
|
|
|
22 Similarly, if there are particular routines that should only be called by
|
|
|
23 the GUI thread, then the analysis will warn if other threads call those
|
|
|
24 routines.
|
|
|
25
|
|
|
26 Getting Started
|
|
|
27 ----------------
|
|
|
28
|
|
|
29 .. code-block:: c++
|
|
|
30
|
|
|
31 #include "mutex.h"
|
|
|
32
|
|
|
33 class BankAccount {
|
|
|
34 private:
|
|
|
35 Mutex mu;
|
|
|
36 int balance GUARDED_BY(mu);
|
|
|
37
|
|
|
38 void depositImpl(int amount) {
|
|
|
39 balance += amount; // WARNING! Cannot write balance without locking mu.
|
|
|
40 }
|
|
|
41
|
|
|
42 void withdrawImpl(int amount) REQUIRES(mu) {
|
|
|
43 balance -= amount; // OK. Caller must have locked mu.
|
|
|
44 }
|
|
|
45
|
|
|
46 public:
|
|
|
47 void withdraw(int amount) {
|
|
|
48 mu.Lock();
|
|
|
49 withdrawImpl(amount); // OK. We've locked mu.
|
|
|
50 } // WARNING! Failed to unlock mu.
|
|
|
51
|
|
|
52 void transferFrom(BankAccount& b, int amount) {
|
|
|
53 mu.Lock();
|
|
|
54 b.withdrawImpl(amount); // WARNING! Calling withdrawImpl() requires locking b.mu.
|
|
|
55 depositImpl(amount); // OK. depositImpl() has no requirements.
|
|
|
56 mu.Unlock();
|
|
|
57 }
|
|
|
58 };
|
|
|
59
|
|
|
60 This example demonstrates the basic concepts behind the analysis. The
|
|
|
61 ``GUARDED_BY`` attribute declares that a thread must lock ``mu`` before it can
|
|
|
62 read or write to ``balance``, thus ensuring that the increment and decrement
|
|
|
63 operations are atomic. Similarly, ``REQUIRES`` declares that
|
|
|
64 the calling thread must lock ``mu`` before calling ``withdrawImpl``.
|
|
|
65 Because the caller is assumed to have locked ``mu``, it is safe to modify
|
|
|
66 ``balance`` within the body of the method.
|
|
|
67
|
|
|
68 The ``depositImpl()`` method does not have ``REQUIRES``, so the
|
|
|
69 analysis issues a warning. Thread safety analysis is not inter-procedural, so
|
|
|
70 caller requirements must be explicitly declared.
|
|
|
71 There is also a warning in ``transferFrom()``, because although the method
|
|
|
72 locks ``this->mu``, it does not lock ``b.mu``. The analysis understands
|
|
|
73 that these are two separate mutexes, in two different objects.
|
|
|
74
|
|
|
75 Finally, there is a warning in the ``withdraw()`` method, because it fails to
|
|
|
76 unlock ``mu``. Every lock must have a corresponding unlock, and the analysis
|
|
|
77 will detect both double locks, and double unlocks. A function is allowed to
|
|
|
78 acquire a lock without releasing it, (or vice versa), but it must be annotated
|
|
|
79 as such (using ``ACQUIRE``/``RELEASE``).
|
|
|
80
|
|
|
81
|
|
|
82 Running The Analysis
|
|
|
83 --------------------
|
|
|
84
|
|
|
85 To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g.
|
|
|
86
|
|
|
87 .. code-block:: bash
|
|
|
88
|
|
|
89 clang -c -Wthread-safety example.cpp
|
|
|
90
|
|
|
91 Note that this example assumes the presence of a suitably annotated
|
|
|
92 :ref:`mutexheader` that declares which methods perform locking,
|
|
|
93 unlocking, and so on.
|
|
|
94
|
|
|
95
|
|
|
96 Basic Concepts: Capabilities
|
|
|
97 ============================
|
|
|
98
|
|
|
99 Thread safety analysis provides a way of protecting *resources* with
|
|
|
100 *capabilities*. A resource is either a data member, or a function/method
|
|
|
101 that provides access to some underlying resource. The analysis ensures that
|
|
|
102 the calling thread cannot access the *resource* (i.e. call the function, or
|
|
|
103 read/write the data) unless it has the *capability* to do so.
|
|
|
104
|
|
|
105 Capabilities are associated with named C++ objects which declare specific
|
|
|
106 methods to acquire and release the capability. The name of the object serves
|
|
|
107 to identify the capability. The most common example is a mutex. For example,
|
|
|
108 if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread
|
|
|
109 to acquire the capability to access data that is protected by ``mu``. Similarly,
|
|
|
110 calling ``mu.Unlock()`` releases that capability.
|
|
|
111
|
|
|
112 A thread may hold a capability either *exclusively* or *shared*. An exclusive
|
|
|
113 capability can be held by only one thread at a time, while a shared capability
|
|
|
114 can be held by many threads at the same time. This mechanism enforces a
|
|
|
115 multiple-reader, single-writer pattern. Write operations to protected data
|
|
|
116 require exclusive access, while read operations require only shared access.
|
|
|
117
|
|
|
118 At any given moment during program execution, a thread holds a specific set of
|
|
|
119 capabilities (e.g. the set of mutexes that it has locked.) These act like keys
|
|
|
120 or tokens that allow the thread to access a given resource. Just like physical
|
|
|
121 security keys, a thread cannot make copy of a capability, nor can it destroy
|
|
|
122 one. A thread can only release a capability to another thread, or acquire one
|
|
|
123 from another thread. The annotations are deliberately agnostic about the
|
|
|
124 exact mechanism used to acquire and release capabilities; it assumes that the
|
|
|
125 underlying implementation (e.g. the Mutex implementation) does the handoff in
|
|
|
126 an appropriate manner.
|
|
|
127
|
|
|
128 The set of capabilities that are actually held by a given thread at a given
|
|
|
129 point in program execution is a run-time concept. The static analysis works
|
|
|
130 by calculating an approximation of that set, called the *capability
|
|
|
131 environment*. The capability environment is calculated for every program point,
|
|
|
132 and describes the set of capabilities that are statically known to be held, or
|
|
|
133 not held, at that particular point. This environment is a conservative
|
|
|
134 approximation of the full set of capabilities that will actually held by a
|
|
|
135 thread at run-time.
|
|
|
136
|
|
|
137
|
|
|
138 Reference Guide
|
|
|
139 ===============
|
|
|
140
|
|
|
141 The thread safety analysis uses attributes to declare threading constraints.
|
|
|
142 Attributes must be attached to named declarations, such as classes, methods,
|
|
|
143 and data members. Users are *strongly advised* to define macros for the various
|
|
|
144 attributes; example definitions can be found in :ref:`mutexheader`, below.
|
|
|
145 The following documentation assumes the use of macros.
|
|
|
146
|
|
|
147 For historical reasons, prior versions of thread safety used macro names that
|
|
|
148 were very lock-centric. These macros have since been renamed to fit a more
|
|
|
149 general capability model. The prior names are still in use, and will be
|
|
|
150 mentioned under the tag *previously* where appropriate.
|
|
|
151
|
|
|
152
|
|
|
153 GUARDED_BY(c) and PT_GUARDED_BY(c)
|
|
|
154 ----------------------------------
|
|
|
155
|
|
|
156 ``GUARDED_BY`` is an attribute on data members, which declares that the data
|
|
|
157 member is protected by the given capability. Read operations on the data
|
|
|
158 require shared access, while write operations require exclusive access.
|
|
|
159
|
|
|
160 ``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart
|
|
|
161 pointers. There is no constraint on the data member itself, but the *data that
|
|
|
162 it points to* is protected by the given capability.
|
|
|
163
|
|
|
164 .. code-block:: c++
|
|
|
165
|
|
|
166 Mutex mu;
|
|
|
167 int *p1 GUARDED_BY(mu);
|
|
|
168 int *p2 PT_GUARDED_BY(mu);
|
|
|
169 unique_ptr<int> p3 PT_GUARDED_BY(mu);
|
|
|
170
|
|
|
171 void test() {
|
|
|
172 p1 = 0; // Warning!
|
|
|
173
|
|
|
174 *p2 = 42; // Warning!
|
|
|
175 p2 = new int; // OK.
|
|
|
176
|
|
|
177 *p3 = 42; // Warning!
|
|
|
178 p3.reset(new int); // OK.
|
|
|
179 }
|
|
|
180
|
|
|
181
|
|
|
182 REQUIRES(...), REQUIRES_SHARED(...)
|
|
|
183 -----------------------------------
|
|
|
184
|
|
|
185 *Previously*: ``EXCLUSIVE_LOCKS_REQUIRED``, ``SHARED_LOCKS_REQUIRED``
|
|
|
186
|
|
|
187 ``REQUIRES`` is an attribute on functions or methods, which
|
|
|
188 declares that the calling thread must have exclusive access to the given
|
|
|
189 capabilities. More than one capability may be specified. The capabilities
|
|
|
190 must be held on entry to the function, *and must still be held on exit*.
|
|
|
191
|
|
|
192 ``REQUIRES_SHARED`` is similar, but requires only shared access.
|
|
|
193
|
|
|
194 .. code-block:: c++
|
|
|
195
|
|
|
196 Mutex mu1, mu2;
|
|
|
197 int a GUARDED_BY(mu1);
|
|
|
198 int b GUARDED_BY(mu2);
|
|
|
199
|
|
|
200 void foo() REQUIRES(mu1, mu2) {
|
|
|
201 a = 0;
|
|
|
202 b = 0;
|
|
|
203 }
|
|
|
204
|
|
|
205 void test() {
|
|
|
206 mu1.Lock();
|
|
|
207 foo(); // Warning! Requires mu2.
|
|
|
208 mu1.Unlock();
|
|
|
209 }
|
|
|
210
|
|
|
211
|
|
|
212 ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...)
|
|
|
213 --------------------------------------------------------------------
|
|
|
214
|
|
|
215 *Previously*: ``EXCLUSIVE_LOCK_FUNCTION``, ``SHARED_LOCK_FUNCTION``,
|
|
|
216 ``UNLOCK_FUNCTION``
|
|
|
217
|
|
|
218 ``ACQUIRE`` is an attribute on functions or methods, which
|
|
|
219 declares that the function acquires a capability, but does not release it. The
|
|
|
220 caller must not hold the given capability on entry, and it will hold the
|
|
|
221 capability on exit. ``ACQUIRE_SHARED`` is similar.
|
|
|
222
|
|
|
223 ``RELEASE`` and ``RELEASE_SHARED`` declare that the function releases the given
|
|
|
224 capability. The caller must hold the capability on entry, and will no longer
|
|
|
225 hold it on exit. It does not matter whether the given capability is shared or
|
|
|
226 exclusive.
|
|
|
227
|
|
|
228 .. code-block:: c++
|
|
|
229
|
|
|
230 Mutex mu;
|
|
|
231 MyClass myObject GUARDED_BY(mu);
|
|
|
232
|
|
|
233 void lockAndInit() ACQUIRE(mu) {
|
|
|
234 mu.Lock();
|
|
|
235 myObject.init();
|
|
|
236 }
|
|
|
237
|
|
|
238 void cleanupAndUnlock() RELEASE(mu) {
|
|
|
239 myObject.cleanup();
|
|
|
240 } // Warning! Need to unlock mu.
|
|
|
241
|
|
|
242 void test() {
|
|
|
243 lockAndInit();
|
|
|
244 myObject.doSomething();
|
|
|
245 cleanupAndUnlock();
|
|
|
246 myObject.doSomething(); // Warning, mu is not locked.
|
|
|
247 }
|
|
|
248
|
|
|
249 If no argument is passed to ``ACQUIRE`` or ``RELEASE``, then the argument is
|
|
|
250 assumed to be ``this``, and the analysis will not check the body of the
|
|
|
251 function. This pattern is intended for use by classes which hide locking
|
|
|
252 details behind an abstract interface. For example:
|
|
|
253
|
|
|
254 .. code-block:: c++
|
|
|
255
|
|
|
256 template <class T>
|
|
|
257 class CAPABILITY("mutex") Container {
|
|
|
258 private:
|
|
|
259 Mutex mu;
|
|
|
260 T* data;
|
|
|
261
|
|
|
262 public:
|
|
|
263 // Hide mu from public interface.
|
|
|
264 void Lock() ACQUIRE() { mu.Lock(); }
|
|
|
265 void Unlock() RELEASE() { mu.Unlock(); }
|
|
|
266
|
|
|
267 T& getElem(int i) { return data[i]; }
|
|
|
268 };
|
|
|
269
|
|
|
270 void test() {
|
|
|
271 Container<int> c;
|
|
|
272 c.Lock();
|
|
|
273 int i = c.getElem(0);
|
|
|
274 c.Unlock();
|
|
|
275 }
|
|
|
276
|
|
|
277
|
|
|
278 EXCLUDES(...)
|
|
|
279 -------------
|
|
|
280
|
|
|
281 *Previously*: ``LOCKS_EXCLUDED``
|
|
|
282
|
|
|
283 ``EXCLUDES`` is an attribute on functions or methods, which declares that
|
|
|
284 the caller must *not* hold the given capabilities. This annotation is
|
|
|
285 used to prevent deadlock. Many mutex implementations are not re-entrant, so
|
|
|
286 deadlock can occur if the function acquires the mutex a second time.
|
|
|
287
|
|
|
288 .. code-block:: c++
|
|
|
289
|
|
|
290 Mutex mu;
|
|
|
291 int a GUARDED_BY(mu);
|
|
|
292
|
|
|
293 void clear() EXCLUDES(mu) {
|
|
|
294 mu.Lock();
|
|
|
295 a = 0;
|
|
|
296 mu.Unlock();
|
|
|
297 }
|
|
|
298
|
|
|
299 void reset() {
|
|
|
300 mu.Lock();
|
|
|
301 clear(); // Warning! Caller cannot hold 'mu'.
|
|
|
302 mu.Unlock();
|
|
|
303 }
|
|
|
304
|
|
|
305 Unlike ``REQUIRES``, ``EXCLUDES`` is optional. The analysis will not issue a
|
|
|
306 warning if the attribute is missing, which can lead to false negatives in some
|
|
|
307 cases. This issue is discussed further in :ref:`negative`.
|
|
|
308
|
|
|
309
|
|
|
310 NO_THREAD_SAFETY_ANALYSIS
|
|
|
311 -------------------------
|
|
|
312
|
|
|
313 ``NO_THREAD_SAFETY_ANALYSIS`` is an attribute on functions or methods, which
|
|
|
314 turns off thread safety checking for that method. It provides an escape hatch
|
|
|
315 for functions which are either (1) deliberately thread-unsafe, or (2) are
|
|
|
316 thread-safe, but too complicated for the analysis to understand. Reasons for
|
|
|
317 (2) will be described in the :ref:`limitations`, below.
|
|
|
318
|
|
|
319 .. code-block:: c++
|
|
|
320
|
|
|
321 class Counter {
|
|
|
322 Mutex mu;
|
|
|
323 int a GUARDED_BY(mu);
|
|
|
324
|
|
|
325 void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
|
|
|
326 };
|
|
|
327
|
|
|
328 Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
|
|
|
329 interface of a function, and should thus be placed on the function definition
|
|
|
330 (in the ``.cc`` or ``.cpp`` file) rather than on the function declaration
|
|
|
331 (in the header).
|
|
|
332
|
|
|
333
|
|
|
334 RETURN_CAPABILITY(c)
|
|
|
335 --------------------
|
|
|
336
|
|
|
337 *Previously*: ``LOCK_RETURNED``
|
|
|
338
|
|
|
339 ``RETURN_CAPABILITY`` is an attribute on functions or methods, which declares
|
|
|
340 that the function returns a reference to the given capability. It is used to
|
|
|
341 annotate getter methods that return mutexes.
|
|
|
342
|
|
|
343 .. code-block:: c++
|
|
|
344
|
|
|
345 class MyClass {
|
|
|
346 private:
|
|
|
347 Mutex mu;
|
|
|
348 int a GUARDED_BY(mu);
|
|
|
349
|
|
|
350 public:
|
|
|
351 Mutex* getMu() RETURN_CAPABILITY(mu) { return μ }
|
|
|
352
|
|
|
353 // analysis knows that getMu() == mu
|
|
|
354 void clear() REQUIRES(getMu()) { a = 0; }
|
|
|
355 };
|
|
|
356
|
|
|
357
|
|
|
358 ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)
|
|
|
359 -----------------------------------------
|
|
|
360
|
|
|
361 ``ACQUIRED_BEFORE`` and ``ACQUIRED_AFTER`` are attributes on member
|
|
|
362 declarations, specifically declarations of mutexes or other capabilities.
|
|
|
363 These declarations enforce a particular order in which the mutexes must be
|
|
|
364 acquired, in order to prevent deadlock.
|
|
|
365
|
|
|
366 .. code-block:: c++
|
|
|
367
|
|
|
368 Mutex m1;
|
|
|
369 Mutex m2 ACQUIRED_AFTER(m1);
|
|
|
370
|
|
|
371 // Alternative declaration
|
|
|
372 // Mutex m2;
|
|
|
373 // Mutex m1 ACQUIRED_BEFORE(m2);
|
|
|
374
|
|
|
375 void foo() {
|
|
|
376 m2.Lock();
|
|
|
377 m1.Lock(); // Warning! m2 must be acquired after m1.
|
|
|
378 m1.Unlock();
|
|
|
379 m2.Unlock();
|
|
|
380 }
|
|
|
381
|
|
|
382
|
|
|
383 CAPABILITY(<string>)
|
|
|
384 --------------------
|
|
|
385
|
|
|
386 *Previously*: ``LOCKABLE``
|
|
|
387
|
|
|
388 ``CAPABILITY`` is an attribute on classes, which specifies that objects of the
|
|
|
389 class can be used as a capability. The string argument specifies the kind of
|
|
|
390 capability in error messages, e.g. ``"mutex"``. See the ``Container`` example
|
|
|
391 given above, or the ``Mutex`` class in :ref:`mutexheader`.
|
|
|
392
|
|
|
393
|
|
|
394 SCOPED_CAPABILITY
|
|
|
395 -----------------
|
|
|
396
|
|
|
397 *Previously*: ``SCOPED_LOCKABLE``
|
|
|
398
|
|
|
399 ``SCOPED_CAPABILITY`` is an attribute on classes that implement RAII-style
|
|
|
400 locking, in which a capability is acquired in the constructor, and released in
|
|
|
401 the destructor. Such classes require special handling because the constructor
|
|
|
402 and destructor refer to the capability via different names; see the
|
|
|
403 ``MutexLocker`` class in :ref:`mutexheader`, below.
|
|
|
404
|
|
|
405
|
|
|
406 TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)
|
|
|
407 ---------------------------------------------------------
|
|
|
408
|
|
|
409 *Previously:* ``EXCLUSIVE_TRYLOCK_FUNCTION``, ``SHARED_TRYLOCK_FUNCTION``
|
|
|
410
|
|
|
411 These are attributes on a function or method that tries to acquire the given
|
|
|
412 capability, and returns a boolean value indicating success or failure.
|
|
|
413 The first argument must be ``true`` or ``false``, to specify which return value
|
|
|
414 indicates success, and the remaining arguments are interpreted in the same way
|
|
|
415 as ``ACQUIRE``. See :ref:`mutexheader`, below, for example uses.
|
|
|
416
|
|
|
417
|
|
|
418 ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)
|
|
|
419 --------------------------------------------------------
|
|
|
420
|
|
|
421 *Previously:* ``ASSERT_EXCLUSIVE_LOCK``, ``ASSERT_SHARED_LOCK``
|
|
|
422
|
|
|
423 These are attributes on a function or method that does a run-time test to see
|
|
|
424 whether the calling thread holds the given capability. The function is assumed
|
|
|
425 to fail (no return) if the capability is not held. See :ref:`mutexheader`,
|
|
|
426 below, for example uses.
|
|
|
427
|
|
|
428
|
|
|
429 GUARDED_VAR and PT_GUARDED_VAR
|
|
|
430 ------------------------------
|
|
|
431
|
|
|
432 Use of these attributes has been deprecated.
|
|
|
433
|
|
|
434
|
|
|
435 Warning flags
|
|
|
436 -------------
|
|
|
437
|
|
|
438 * ``-Wthread-safety``: Umbrella flag which turns on the following three:
|
|
|
439
|
|
|
440 + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax.
|
|
|
441 + ``-Wthread-safety-analysis``: The core analysis.
|
|
|
442 + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely.
|
|
|
443 This warning can be disabled for code which has a lot of aliases.
|
|
|
444 + ``-Wthread-safety-reference``: Checks when guarded members are passed by reference.
|
|
|
445
|
|
|
446
|
|
|
447 :ref:`negative` are an experimental feature, which are enabled with:
|
|
|
448
|
|
|
449 * ``-Wthread-safety-negative``: Negative capabilities. Off by default.
|
|
|
450
|
|
|
451 When new features and checks are added to the analysis, they can often introduce
|
|
|
452 additional warnings. Those warnings are initially released as *beta* warnings
|
|
|
453 for a period of time, after which they are migrated into the standard analysis.
|
|
|
454
|
|
|
455 * ``-Wthread-safety-beta``: New features. Off by default.
|
|
|
456
|
|
|
457
|
|
|
458 .. _negative:
|
|
|
459
|
|
|
460 Negative Capabilities
|
|
|
461 =====================
|
|
|
462
|
|
|
463 Thread Safety Analysis is designed to prevent both race conditions and
|
|
|
464 deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by
|
|
|
465 ensuring that a capability is held before reading or writing to guarded data,
|
|
|
466 and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
|
|
|
467 *not* held.
|
|
|
468
|
|
|
469 However, EXCLUDES is an optional attribute, and does not provide the same
|
|
|
470 safety guarantee as REQUIRES. In particular:
|
|
|
471
|
|
|
472 * A function which acquires a capability does not have to exclude it.
|
|
|
473 * A function which calls a function that excludes a capability does not
|
|
|
474 have transitively exclude that capability.
|
|
|
475
|
|
|
476 As a result, EXCLUDES can easily produce false negatives:
|
|
|
477
|
|
|
478 .. code-block:: c++
|
|
|
479
|
|
|
480 class Foo {
|
|
|
481 Mutex mu;
|
|
|
482
|
|
|
483 void foo() {
|
|
|
484 mu.Lock();
|
|
|
485 bar(); // No warning.
|
|
|
486 baz(); // No warning.
|
|
|
487 mu.Unlock();
|
|
|
488 }
|
|
|
489
|
|
|
490 void bar() { // No warning. (Should have EXCLUDES(mu)).
|
|
|
491 mu.Lock();
|
|
|
492 // ...
|
|
|
493 mu.Unlock();
|
|
|
494 }
|
|
|
495
|
|
|
496 void baz() {
|
|
|
497 bif(); // No warning. (Should have EXCLUDES(mu)).
|
|
|
498 }
|
|
|
499
|
|
|
500 void bif() EXCLUDES(mu);
|
|
|
501 };
|
|
|
502
|
|
|
503
|
|
|
504 Negative requirements are an alternative EXCLUDES that provide
|
|
|
505 a stronger safety guarantee. A negative requirement uses the REQUIRES
|
|
|
506 attribute, in conjunction with the ``!`` operator, to indicate that a capability
|
|
|
507 should *not* be held.
|
|
|
508
|
|
|
509 For example, using ``REQUIRES(!mu)`` instead of ``EXCLUDES(mu)`` will produce
|
|
|
510 the appropriate warnings:
|
|
|
511
|
|
|
512 .. code-block:: c++
|
|
|
513
|
|
|
514 class FooNeg {
|
|
|
515 Mutex mu;
|
|
|
516
|
|
|
517 void foo() REQUIRES(!mu) { // foo() now requires !mu.
|
|
|
518 mu.Lock();
|
|
|
519 bar();
|
|
|
520 baz();
|
|
|
521 mu.Unlock();
|
|
|
522 }
|
|
|
523
|
|
|
524 void bar() {
|
|
|
525 mu.Lock(); // WARNING! Missing REQUIRES(!mu).
|
|
|
526 // ...
|
|
|
527 mu.Unlock();
|
|
|
528 }
|
|
|
529
|
|
|
530 void baz() {
|
|
|
531 bif(); // WARNING! Missing REQUIRES(!mu).
|
|
|
532 }
|
|
|
533
|
|
|
534 void bif() REQUIRES(!mu);
|
|
|
535 };
|
|
|
536
|
|
|
537
|
|
|
538 Negative requirements are an experimental feature which is off by default,
|
|
|
539 because it will produce many warnings in existing code. It can be enabled
|
|
|
540 by passing ``-Wthread-safety-negative``.
|
|
|
541
|
|
|
542
|
|
|
543 .. _faq:
|
|
|
544
|
|
|
545 Frequently Asked Questions
|
|
|
546 ==========================
|
|
|
547
|
|
|
548 (Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
|
|
|
549
|
|
|
550 (A) Attributes are part of the formal interface of a function, and should
|
|
|
551 always go in the header, where they are visible to anything that includes
|
|
|
552 the header. Attributes in the .cpp file are not visible outside of the
|
|
|
553 immediate translation unit, which leads to false negatives and false positives.
|
|
|
554
|
|
|
555
|
|
|
556 (Q) "*Mutex is not locked on every path through here?*" What does that mean?
|
|
|
557
|
|
|
558 (A) See :ref:`conditional_locks`, below.
|
|
|
559
|
|
|
560
|
|
|
561 .. _limitations:
|
|
|
562
|
|
|
563 Known Limitations
|
|
|
564 =================
|
|
|
565
|
|
|
566 Lexical scope
|
|
|
567 -------------
|
|
|
568
|
|
|
569 Thread safety attributes contain ordinary C++ expressions, and thus follow
|
|
|
570 ordinary C++ scoping rules. In particular, this means that mutexes and other
|
|
|
571 capabilities must be declared before they can be used in an attribute.
|
|
|
572 Use-before-declaration is okay within a single class, because attributes are
|
|
|
573 parsed at the same time as method bodies. (C++ delays parsing of method bodies
|
|
|
574 until the end of the class.) However, use-before-declaration is not allowed
|
|
|
575 between classes, as illustrated below.
|
|
|
576
|
|
|
577 .. code-block:: c++
|
|
|
578
|
|
|
579 class Foo;
|
|
|
580
|
|
|
581 class Bar {
|
|
|
582 void bar(Foo* f) REQUIRES(f->mu); // Error: mu undeclared.
|
|
|
583 };
|
|
|
584
|
|
|
585 class Foo {
|
|
|
586 Mutex mu;
|
|
|
587 };
|
|
|
588
|
|
|
589
|
|
|
590 Private Mutexes
|
|
|
591 ---------------
|
|
|
592
|
|
|
593 Good software engineering practice dictates that mutexes should be private
|
|
|
594 members, because the locking mechanism used by a thread-safe class is part of
|
|
|
595 its internal implementation. However, private mutexes can sometimes leak into
|
|
|
596 the public interface of a class.
|
|
|
597 Thread safety attributes follow normal C++ access restrictions, so if ``mu``
|
|
|
598 is a private member of ``c``, then it is an error to write ``c.mu`` in an
|
|
|
599 attribute.
|
|
|
600
|
|
|
601 One workaround is to (ab)use the ``RETURN_CAPABILITY`` attribute to provide a
|
|
|
602 public *name* for a private mutex, without actually exposing the underlying
|
|
|
603 mutex. For example:
|
|
|
604
|
|
|
605 .. code-block:: c++
|
|
|
606
|
|
|
607 class MyClass {
|
|
|
608 private:
|
|
|
609 Mutex mu;
|
|
|
610
|
|
|
611 public:
|
|
|
612 // For thread safety analysis only. Does not actually return mu.
|
|
|
613 Mutex* getMu() RETURN_CAPABILITY(mu) { return 0; }
|
|
|
614
|
|
|
615 void doSomething() REQUIRES(mu);
|
|
|
616 };
|
|
|
617
|
|
|
618 void doSomethingTwice(MyClass& c) REQUIRES(c.getMu()) {
|
|
|
619 // The analysis thinks that c.getMu() == c.mu
|
|
|
620 c.doSomething();
|
|
|
621 c.doSomething();
|
|
|
622 }
|
|
|
623
|
|
|
624 In the above example, ``doSomethingTwice()`` is an external routine that
|
|
|
625 requires ``c.mu`` to be locked, which cannot be declared directly because ``mu``
|
|
|
626 is private. This pattern is discouraged because it
|
|
|
627 violates encapsulation, but it is sometimes necessary, especially when adding
|
|
|
628 annotations to an existing code base. The workaround is to define ``getMu()``
|
|
|
629 as a fake getter method, which is provided only for the benefit of thread
|
|
|
630 safety analysis.
|
|
|
631
|
|
|
632
|
|
|
633 .. _conditional_locks:
|
|
|
634
|
|
|
635 No conditionally held locks.
|
|
|
636 ----------------------------
|
|
|
637
|
|
|
638 The analysis must be able to determine whether a lock is held, or not held, at
|
|
|
639 every program point. Thus, sections of code where a lock *might be held* will
|
|
|
640 generate spurious warnings (false positives). For example:
|
|
|
641
|
|
|
642 .. code-block:: c++
|
|
|
643
|
|
|
644 void foo() {
|
|
|
645 bool b = needsToLock();
|
|
|
646 if (b) mu.Lock();
|
|
|
647 ... // Warning! Mutex 'mu' is not held on every path through here.
|
|
|
648 if (b) mu.Unlock();
|
|
|
649 }
|
|
|
650
|
|
|
651
|
|
|
652 No checking inside constructors and destructors.
|
|
|
653 ------------------------------------------------
|
|
|
654
|
|
|
655 The analysis currently does not do any checking inside constructors or
|
|
|
656 destructors. In other words, every constructor and destructor is treated as
|
|
|
657 if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``.
|
|
|
658 The reason for this is that during initialization, only one thread typically
|
|
|
659 has access to the object which is being initialized, and it is thus safe (and
|
|
|
660 common practice) to initialize guarded members without acquiring any locks.
|
|
|
661 The same is true of destructors.
|
|
|
662
|
|
|
663 Ideally, the analysis would allow initialization of guarded members inside the
|
|
|
664 object being initialized or destroyed, while still enforcing the usual access
|
|
|
665 restrictions on everything else. However, this is difficult to enforce in
|
|
|
666 practice, because in complex pointer-based data structures, it is hard to
|
|
|
667 determine what data is owned by the enclosing object.
|
|
|
668
|
|
|
669 No inlining.
|
|
|
670 ------------
|
|
|
671
|
|
|
672 Thread safety analysis is strictly intra-procedural, just like ordinary type
|
|
|
673 checking. It relies only on the declared attributes of a function, and will
|
|
|
674 not attempt to inline any method calls. As a result, code such as the
|
|
|
675 following will not work:
|
|
|
676
|
|
|
677 .. code-block:: c++
|
|
|
678
|
|
|
679 template<class T>
|
|
|
680 class AutoCleanup {
|
|
|
681 T* object;
|
|
|
682 void (T::*mp)();
|
|
|
683
|
|
|
684 public:
|
|
|
685 AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
|
|
|
686 ~AutoCleanup() { (object->*mp)(); }
|
|
|
687 };
|
|
|
688
|
|
|
689 Mutex mu;
|
|
|
690 void foo() {
|
|
|
691 mu.Lock();
|
|
|
692 AutoCleanup<Mutex>(&mu, &Mutex::Unlock);
|
|
|
693 // ...
|
|
|
694 } // Warning, mu is not unlocked.
|
|
|
695
|
|
|
696 In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so
|
|
|
697 the warning is bogus. However,
|
|
|
698 thread safety analysis cannot see the unlock, because it does not attempt to
|
|
|
699 inline the destructor. Moreover, there is no way to annotate the destructor,
|
|
|
700 because the destructor is calling a function that is not statically known.
|
|
|
701 This pattern is simply not supported.
|
|
|
702
|
|
|
703
|
|
|
704 No alias analysis.
|
|
|
705 ------------------
|
|
|
706
|
|
|
707 The analysis currently does not track pointer aliases. Thus, there can be
|
|
|
708 false positives if two pointers both point to the same mutex.
|
|
|
709
|
|
|
710
|
|
|
711 .. code-block:: c++
|
|
|
712
|
|
|
713 class MutexUnlocker {
|
|
|
714 Mutex* mu;
|
|
|
715
|
|
|
716 public:
|
|
|
717 MutexUnlocker(Mutex* m) RELEASE(m) : mu(m) { mu->Unlock(); }
|
|
|
718 ~MutexUnlocker() ACQUIRE(mu) { mu->Lock(); }
|
|
|
719 };
|
|
|
720
|
|
|
721 Mutex mutex;
|
|
|
722 void test() REQUIRES(mutex) {
|
|
|
723 {
|
|
|
724 MutexUnlocker munl(&mutex); // unlocks mutex
|
|
|
725 doSomeIO();
|
|
|
726 } // Warning: locks munl.mu
|
|
|
727 }
|
|
|
728
|
|
|
729 The MutexUnlocker class is intended to be the dual of the MutexLocker class,
|
|
|
730 defined in :ref:`mutexheader`. However, it doesn't work because the analysis
|
|
|
731 doesn't know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles
|
|
|
732 aliasing for MutexLocker, but does so only for that particular pattern.
|
|
|
733
|
|
|
734
|
|
|
735 ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
|
|
|
736 -------------------------------------------------------------------------
|
|
|
737
|
|
|
738 To be fixed in a future update.
|
|
|
739
|
|
|
740
|
|
|
741 .. _mutexheader:
|
|
|
742
|
|
|
743 mutex.h
|
|
|
744 =======
|
|
|
745
|
|
|
746 Thread safety analysis can be used with any threading library, but it does
|
|
|
747 require that the threading API be wrapped in classes and methods which have the
|
|
|
748 appropriate annotations. The following code provides ``mutex.h`` as an example;
|
|
|
749 these methods should be filled in to call the appropriate underlying
|
|
|
750 implementation.
|
|
|
751
|
|
|
752
|
|
|
753 .. code-block:: c++
|
|
|
754
|
|
|
755
|
|
|
756 #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
|
757 #define THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
|
758
|
|
|
759 // Enable thread safety attributes only with clang.
|
|
|
760 // The attributes can be safely erased when compiling with other compilers.
|
|
|
761 #if defined(__clang__) && (!defined(SWIG))
|
|
|
762 #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
|
|
|
763 #else
|
|
|
764 #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
|
|
|
765 #endif
|
|
|
766
|
|
|
767 #define CAPABILITY(x) \
|
|
|
768 THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
|
|
|
769
|
|
|
770 #define SCOPED_CAPABILITY \
|
|
|
771 THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
|
|
|
772
|
|
|
773 #define GUARDED_BY(x) \
|
|
|
774 THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
|
|
|
775
|
|
|
776 #define PT_GUARDED_BY(x) \
|
|
|
777 THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
|
|
|
778
|
|
|
779 #define ACQUIRED_BEFORE(...) \
|
|
|
780 THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
|
|
|
781
|
|
|
782 #define ACQUIRED_AFTER(...) \
|
|
|
783 THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
|
|
|
784
|
|
|
785 #define REQUIRES(...) \
|
|
|
786 THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))
|
|
|
787
|
|
|
788 #define REQUIRES_SHARED(...) \
|
|
|
789 THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))
|
|
|
790
|
|
|
791 #define ACQUIRE(...) \
|
|
|
792 THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))
|
|
|
793
|
|
|
794 #define ACQUIRE_SHARED(...) \
|
|
|
795 THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
|
|
|
796
|
|
|
797 #define RELEASE(...) \
|
|
|
798 THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
|
|
|
799
|
|
|
800 #define RELEASE_SHARED(...) \
|
|
|
801 THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
|
|
|
802
|
|
|
803 #define TRY_ACQUIRE(...) \
|
|
|
804 THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
|
|
|
805
|
|
|
806 #define TRY_ACQUIRE_SHARED(...) \
|
|
|
807 THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
|
|
|
808
|
|
|
809 #define EXCLUDES(...) \
|
|
|
810 THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
|
|
|
811
|
|
|
812 #define ASSERT_CAPABILITY(x) \
|
|
|
813 THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
|
|
|
814
|
|
|
815 #define ASSERT_SHARED_CAPABILITY(x) \
|
|
|
816 THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
|
|
|
817
|
|
|
818 #define RETURN_CAPABILITY(x) \
|
|
|
819 THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
|
|
|
820
|
|
|
821 #define NO_THREAD_SAFETY_ANALYSIS \
|
|
|
822 THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
|
|
|
823
|
|
|
824
|
|
|
825 // Defines an annotated interface for mutexes.
|
|
|
826 // These methods can be implemented to use any internal mutex implementation.
|
|
|
827 class CAPABILITY("mutex") Mutex {
|
|
|
828 public:
|
|
|
829 // Acquire/lock this mutex exclusively. Only one thread can have exclusive
|
|
|
830 // access at any one time. Write operations to guarded data require an
|
|
|
831 // exclusive lock.
|
|
|
832 void Lock() ACQUIRE();
|
|
|
833
|
|
|
834 // Acquire/lock this mutex for read operations, which require only a shared
|
|
|
835 // lock. This assumes a multiple-reader, single writer semantics. Multiple
|
|
|
836 // threads may acquire the mutex simultaneously as readers, but a writer
|
|
|
837 // must wait for all of them to release the mutex before it can acquire it
|
|
|
838 // exclusively.
|
|
|
839 void ReaderLock() ACQUIRE_SHARED();
|
|
|
840
|
|
|
841 // Release/unlock an exclusive mutex.
|
|
|
842 void Unlock() RELEASE();
|
|
|
843
|
|
|
844 // Release/unlock a shared mutex.
|
|
|
845 void ReaderUnlock() RELEASE_SHARED();
|
|
|
846
|
|
|
847 // Try to acquire the mutex. Returns true on success, and false on failure.
|
|
|
848 bool TryLock() TRY_ACQUIRE(true);
|
|
|
849
|
|
|
850 // Try to acquire the mutex for read operations.
|
|
|
851 bool ReaderTryLock() TRY_ACQUIRE_SHARED(true);
|
|
|
852
|
|
|
853 // Assert that this mutex is currently held by the calling thread.
|
|
|
854 void AssertHeld() ASSERT_CAPABILITY(this);
|
|
|
855
|
|
|
856 // Assert that is mutex is currently held for read operations.
|
|
|
857 void AssertReaderHeld() ASSERT_SHARED_CAPABILITY(this);
|
|
|
858
|
|
|
859 // For negative capabilities.
|
|
|
860 const Mutex& operator!() const { return *this; }
|
|
|
861 };
|
|
|
862
|
|
|
863
|
|
|
864 // MutexLocker is an RAII class that acquires a mutex in its constructor, and
|
|
|
865 // releases it in its destructor.
|
|
|
866 class SCOPED_CAPABILITY MutexLocker {
|
|
|
867 private:
|
|
|
868 Mutex* mut;
|
|
|
869
|
|
|
870 public:
|
|
|
871 MutexLocker(Mutex *mu) ACQUIRE(mu) : mut(mu) {
|
|
|
872 mu->Lock();
|
|
|
873 }
|
|
|
874 ~MutexLocker() RELEASE() {
|
|
|
875 mut->Unlock();
|
|
|
876 }
|
|
|
877 };
|
|
|
878
|
|
|
879
|
|
|
880 #ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
|
|
|
881 // The original version of thread safety analysis the following attribute
|
|
|
882 // definitions. These use a lock-based terminology. They are still in use
|
|
|
883 // by existing thread safety code, and will continue to be supported.
|
|
|
884
|
|
|
885 // Deprecated.
|
|
|
886 #define PT_GUARDED_VAR \
|
|
|
887 THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_var)
|
|
|
888
|
|
|
889 // Deprecated.
|
|
|
890 #define GUARDED_VAR \
|
|
|
891 THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)
|
|
|
892
|
|
|
893 // Replaced by REQUIRES
|
|
|
894 #define EXCLUSIVE_LOCKS_REQUIRED(...) \
|
|
|
895 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
|
|
|
896
|
|
|
897 // Replaced by REQUIRES_SHARED
|
|
|
898 #define SHARED_LOCKS_REQUIRED(...) \
|
|
|
899 THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
|
|
|
900
|
|
|
901 // Replaced by CAPABILITY
|
|
|
902 #define LOCKABLE \
|
|
|
903 THREAD_ANNOTATION_ATTRIBUTE__(lockable)
|
|
|
904
|
|
|
905 // Replaced by SCOPED_CAPABILITY
|
|
|
906 #define SCOPED_LOCKABLE \
|
|
|
907 THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
|
|
|
908
|
|
|
909 // Replaced by ACQUIRE
|
|
|
910 #define EXCLUSIVE_LOCK_FUNCTION(...) \
|
|
|
911 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
|
|
|
912
|
|
|
913 // Replaced by ACQUIRE_SHARED
|
|
|
914 #define SHARED_LOCK_FUNCTION(...) \
|
|
|
915 THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
|
|
|
916
|
|
|
917 // Replaced by RELEASE and RELEASE_SHARED
|
|
|
918 #define UNLOCK_FUNCTION(...) \
|
|
|
919 THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
|
|
|
920
|
|
|
921 // Replaced by TRY_ACQUIRE
|
|
|
922 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
|
|
|
923 THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
|
|
|
924
|
|
|
925 // Replaced by TRY_ACQUIRE_SHARED
|
|
|
926 #define SHARED_TRYLOCK_FUNCTION(...) \
|
|
|
927 THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
|
|
|
928
|
|
|
929 // Replaced by ASSERT_CAPABILITY
|
|
|
930 #define ASSERT_EXCLUSIVE_LOCK(...) \
|
|
|
931 THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
|
|
|
932
|
|
|
933 // Replaced by ASSERT_SHARED_CAPABILITY
|
|
|
934 #define ASSERT_SHARED_LOCK(...) \
|
|
|
935 THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
|
|
|
936
|
|
|
937 // Replaced by EXCLUDE_CAPABILITY.
|
|
|
938 #define LOCKS_EXCLUDED(...) \
|
|
|
939 THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
|
|
|
940
|
|
|
941 // Replaced by RETURN_CAPABILITY
|
|
|
942 #define LOCK_RETURNED(x) \
|
|
|
943 THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
|
|
|
944
|
|
|
945 #endif // USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
|
|
|
946
|
|
|
947 #endif // THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
|
948
|
