clang/docs/ThreadSafetyAnalysis.rst

   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 The attributes only control assumptions made by thread safety analysis and the
 148 warnings it issues.  They don't affect generated code or behavior at run-time.
 149
 150 For historical reasons, prior versions of thread safety used macro names that
 151 were very lock-centric.  These macros have since been renamed to fit a more
 152 general capability model.  The prior names are still in use, and will be
 153 mentioned under the tag *previously* where appropriate.
 154
 155
 156 GUARDED_BY(c) and PT_GUARDED_BY(c)
 157 ----------------------------------
 158
 159 ``GUARDED_BY`` is an attribute on data members, which declares that the data
 160 member is protected by the given capability.  Read operations on the data
 161 require shared access, while write operations require exclusive access.
 162
 163 ``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart
 164 pointers. There is no constraint on the data member itself, but the *data that
 165 it points to* is protected by the given capability.
 166
 167 .. code-block:: c++
 168
 169   Mutex mu;
 170   int *p1             GUARDED_BY(mu);
 171   int *p2             PT_GUARDED_BY(mu);
 172   unique_ptr<int> p3  PT_GUARDED_BY(mu);
 173
 174   void test() {
 175     p1 = 0;             // Warning!
 176
 177     *p2 = 42;           // Warning!
 178     p2 = new int;       // OK.
 179
 180     *p3 = 42;           // Warning!
 181     p3.reset(new int);  // OK.
 182   }
 183
 184
 185 REQUIRES(...), REQUIRES_SHARED(...)
 186 -----------------------------------
 187
 188 *Previously*: ``EXCLUSIVE_LOCKS_REQUIRED``, ``SHARED_LOCKS_REQUIRED``
 189
 190 ``REQUIRES`` is an attribute on functions or methods, which
 191 declares that the calling thread must have exclusive access to the given
 192 capabilities.  More than one capability may be specified.  The capabilities
 193 must be held on entry to the function, *and must still be held on exit*.
 194
 195 ``REQUIRES_SHARED`` is similar, but requires only shared access.
 196
 197 .. code-block:: c++
 198
 199   Mutex mu1, mu2;
 200   int a GUARDED_BY(mu1);
 201   int b GUARDED_BY(mu2);
 202
 203   void foo() REQUIRES(mu1, mu2) {
 204     a = 0;
 205     b = 0;
 206   }
 207
 208   void test() {
 209     mu1.Lock();
 210     foo();         // Warning!  Requires mu2.
 211     mu1.Unlock();
 212   }
 213
 214
 215 ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...), RELEASE_GENERIC(...)
 216 ------------------------------------------------------------------------------------------
 217
 218 *Previously*: ``EXCLUSIVE_LOCK_FUNCTION``, ``SHARED_LOCK_FUNCTION``,
 219 ``UNLOCK_FUNCTION``
 220
 221 ``ACQUIRE`` and ``ACQUIRE_SHARED`` are attributes on functions or methods
 222 declaring that the function acquires a capability, but does not release it.
 223 The given capability must not be held on entry, and will be held on exit
 224 (exclusively for ``ACQUIRE``, shared for ``ACQUIRE_SHARED``).
 225
 226 ``RELEASE``, ``RELEASE_SHARED``, and ``RELEASE_GENERIC`` declare that the
 227 function releases the given capability.  The capability must be held on entry
 228 (exclusively for ``RELEASE``, shared for ``RELEASE_SHARED``, exclusively or
 229 shared for ``RELEASE_GENERIC``), and will no longer be held on exit.
 230
 231 .. code-block:: c++
 232
 233   Mutex mu;
 234   MyClass myObject GUARDED_BY(mu);
 235
 236   void lockAndInit() ACQUIRE(mu) {
 237     mu.Lock();
 238     myObject.init();
 239   }
 240
 241   void cleanupAndUnlock() RELEASE(mu) {
 242     myObject.cleanup();
 243   }                          // Warning!  Need to unlock mu.
 244
 245   void test() {
 246     lockAndInit();
 247     myObject.doSomething();
 248     cleanupAndUnlock();
 249     myObject.doSomething();  // Warning, mu is not locked.
 250   }
 251
 252 If no argument is passed to ``ACQUIRE`` or ``RELEASE``, then the argument is
 253 assumed to be ``this``, and the analysis will not check the body of the
 254 function.  This pattern is intended for use by classes which hide locking
 255 details behind an abstract interface.  For example:
 256
 257 .. code-block:: c++
 258
 259   template <class T>
 260   class CAPABILITY("mutex") Container {
 261   private:
 262     Mutex mu;
 263     T* data;
 264
 265   public:
 266     // Hide mu from public interface.
 267     void Lock()   ACQUIRE() { mu.Lock(); }
 268     void Unlock() RELEASE() { mu.Unlock(); }
 269
 270     T& getElem(int i) { return data[i]; }
 271   };
 272
 273   void test() {
 274     Container<int> c;
 275     c.Lock();
 276     int i = c.getElem(0);
 277     c.Unlock();
 278   }
 279
 280
 281 EXCLUDES(...)
 282 -------------
 283
 284 *Previously*: ``LOCKS_EXCLUDED``
 285
 286 ``EXCLUDES`` is an attribute on functions or methods, which declares that
 287 the caller must *not* hold the given capabilities.  This annotation is
 288 used to prevent deadlock.  Many mutex implementations are not re-entrant, so
 289 deadlock can occur if the function acquires the mutex a second time.
 290
 291 .. code-block:: c++
 292
 293   Mutex mu;
 294   int a GUARDED_BY(mu);
 295
 296   void clear() EXCLUDES(mu) {
 297     mu.Lock();
 298     a = 0;
 299     mu.Unlock();
 300   }
 301
 302   void reset() {
 303     mu.Lock();
 304     clear();     // Warning!  Caller cannot hold 'mu'.
 305     mu.Unlock();
 306   }
 307
 308 Unlike ``REQUIRES``, ``EXCLUDES`` is optional.  The analysis will not issue a
 309 warning if the attribute is missing, which can lead to false negatives in some
 310 cases.  This issue is discussed further in :ref:`negative`.
 311
 312
 313 NO_THREAD_SAFETY_ANALYSIS
 314 -------------------------
 315
 316 ``NO_THREAD_SAFETY_ANALYSIS`` is an attribute on functions or methods, which
 317 turns off thread safety checking for that method.  It provides an escape hatch
 318 for functions which are either (1) deliberately thread-unsafe, or (2) are
 319 thread-safe, but too complicated for the analysis to understand.  Reasons for
 320 (2) will be described in the :ref:`limitations`, below.
 321
 322 .. code-block:: c++
 323
 324   class Counter {
 325     Mutex mu;
 326     int a GUARDED_BY(mu);
 327
 328     void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
 329   };
 330
 331 Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
 332 interface of a function, and should thus be placed on the function definition
 333 (in the ``.cc`` or ``.cpp`` file) rather than on the function declaration
 334 (in the header).
 335
 336
 337 RETURN_CAPABILITY(c)
 338 --------------------
 339
 340 *Previously*: ``LOCK_RETURNED``
 341
 342 ``RETURN_CAPABILITY`` is an attribute on functions or methods, which declares
 343 that the function returns a reference to the given capability.  It is used to
 344 annotate getter methods that return mutexes.
 345
 346 .. code-block:: c++
 347
 348   class MyClass {
 349   private:
 350     Mutex mu;
 351     int a GUARDED_BY(mu);
 352
 353   public:
 354     Mutex* getMu() RETURN_CAPABILITY(mu) { return &mu; }
 355
 356     // analysis knows that getMu() == mu
 357     void clear() REQUIRES(getMu()) { a = 0; }
 358   };
 359
 360
 361 ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)
 362 -----------------------------------------
 363
 364 ``ACQUIRED_BEFORE`` and ``ACQUIRED_AFTER`` are attributes on member
 365 declarations, specifically declarations of mutexes or other capabilities.
 366 These declarations enforce a particular order in which the mutexes must be
 367 acquired, in order to prevent deadlock.
 368
 369 .. code-block:: c++
 370
 371   Mutex m1;
 372   Mutex m2 ACQUIRED_AFTER(m1);
 373
 374   // Alternative declaration
 375   // Mutex m2;
 376   // Mutex m1 ACQUIRED_BEFORE(m2);
 377
 378   void foo() {
 379     m2.Lock();
 380     m1.Lock();  // Warning!  m2 must be acquired after m1.
 381     m1.Unlock();
 382     m2.Unlock();
 383   }
 384
 385
 386 CAPABILITY(<string>)
 387 --------------------
 388
 389 *Previously*: ``LOCKABLE``
 390
 391 ``CAPABILITY`` is an attribute on classes, which specifies that objects of the
 392 class can be used as a capability.  The string argument specifies the kind of
 393 capability in error messages, e.g. ``"mutex"``.  See the ``Container`` example
 394 given above, or the ``Mutex`` class in :ref:`mutexheader`.
 395
 396
 397 SCOPED_CAPABILITY
 398 -----------------
 399
 400 *Previously*: ``SCOPED_LOCKABLE``
 401
 402 ``SCOPED_CAPABILITY`` is an attribute on classes that implement RAII-style
 403 locking, in which a capability is acquired in the constructor, and released in
 404 the destructor.  Such classes require special handling because the constructor
 405 and destructor refer to the capability via different names; see the
 406 ``MutexLocker`` class in :ref:`mutexheader`, below.
 407
 408 Scoped capabilities are treated as capabilities that are implicitly acquired
 409 on construction and released on destruction. They are associated with
 410 the set of (regular) capabilities named in thread safety attributes on the
 411 constructor. Acquire-type attributes on other member functions are treated as
 412 applying to that set of associated capabilities, while ``RELEASE`` implies that
 413 a function releases all associated capabilities in whatever mode they're held.
 414
 415
 416 TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)
 417 ---------------------------------------------------------
 418
 419 *Previously:* ``EXCLUSIVE_TRYLOCK_FUNCTION``, ``SHARED_TRYLOCK_FUNCTION``
 420
 421 These are attributes on a function or method that tries to acquire the given
 422 capability, and returns a boolean value indicating success or failure.
 423 The first argument must be ``true`` or ``false``, to specify which return value
 424 indicates success, and the remaining arguments are interpreted in the same way
 425 as ``ACQUIRE``.  See :ref:`mutexheader`, below, for example uses.
 426
 427 Because the analysis doesn't support conditional locking, a capability is
 428 treated as acquired after the first branch on the return value of a try-acquire
 429 function.
 430
 431 .. code-block:: c++
 432
 433   Mutex mu;
 434   int a GUARDED_BY(mu);
 435
 436   void foo() {
 437     bool success = mu.TryLock();
 438     a = 0;         // Warning, mu is not locked.
 439     if (success) {
 440       a = 0;       // Ok.
 441       mu.Unlock();
 442     } else {
 443       a = 0;       // Warning, mu is not locked.
 444     }
 445   }
 446
 447
 448 ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)
 449 --------------------------------------------------------
 450
 451 *Previously:*  ``ASSERT_EXCLUSIVE_LOCK``, ``ASSERT_SHARED_LOCK``
 452
 453 These are attributes on a function or method which asserts the calling thread
 454 already holds the given capability, for example by performing a run-time test
 455 and terminating if the capability is not held.  Presence of this annotation
 456 causes the analysis to assume the capability is held after calls to the
 457 annotated function.  See :ref:`mutexheader`, below, for example uses.
 458
 459
 460 GUARDED_VAR and PT_GUARDED_VAR
 461 ------------------------------
 462
 463 Use of these attributes has been deprecated.
 464
 465
 466 Warning flags
 467 -------------
 468
 469 * ``-Wthread-safety``:  Umbrella flag which turns on the following three:
 470
 471   + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax.
 472   + ``-Wthread-safety-analysis``: The core analysis.
 473   + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely.
 474        This warning can be disabled for code which has a lot of aliases.
 475   + ``-Wthread-safety-reference``: Checks when guarded members are passed by reference.
 476
 477
 478 :ref:`negative` are an experimental feature, which are enabled with:
 479
 480 * ``-Wthread-safety-negative``:  Negative capabilities.  Off by default.
 481
 482 When new features and checks are added to the analysis, they can often introduce
 483 additional warnings.  Those warnings are initially released as *beta* warnings
 484 for a period of time, after which they are migrated into the standard analysis.
 485
 486 * ``-Wthread-safety-beta``:  New features.  Off by default.
 487
 488
 489 .. _negative:
 490
 491 Negative Capabilities
 492 =====================
 493
 494 Thread Safety Analysis is designed to prevent both race conditions and
 495 deadlock.  The GUARDED_BY and REQUIRES attributes prevent race conditions, by
 496 ensuring that a capability is held before reading or writing to guarded data,
 497 and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
 498 *not* held.
 499
 500 However, EXCLUDES is an optional attribute, and does not provide the same
 501 safety guarantee as REQUIRES.  In particular:
 502
 503   * A function which acquires a capability does not have to exclude it.
 504   * A function which calls a function that excludes a capability does not
 505     have transitively exclude that capability.
 506
 507 As a result, EXCLUDES can easily produce false negatives:
 508
 509 .. code-block:: c++
 510
 511   class Foo {
 512     Mutex mu;
 513
 514     void foo() {
 515       mu.Lock();
 516       bar();           // No warning.
 517       baz();           // No warning.
 518       mu.Unlock();
 519     }
 520
 521     void bar() {       // No warning.  (Should have EXCLUDES(mu)).
 522       mu.Lock();
 523       // ...
 524       mu.Unlock();
 525     }
 526
 527     void baz() {
 528       bif();           // No warning.  (Should have EXCLUDES(mu)).
 529     }
 530
 531     void bif() EXCLUDES(mu);
 532   };
 533
 534
 535 Negative requirements are an alternative EXCLUDES that provide
 536 a stronger safety guarantee.  A negative requirement uses the  REQUIRES
 537 attribute, in conjunction with the ``!`` operator, to indicate that a capability
 538 should *not* be held.
 539
 540 For example, using ``REQUIRES(!mu)`` instead of ``EXCLUDES(mu)`` will produce
 541 the appropriate warnings:
 542
 543 .. code-block:: c++
 544
 545   class FooNeg {
 546     Mutex mu;
 547
 548     void foo() REQUIRES(!mu) {   // foo() now requires !mu.
 549       mu.Lock();
 550       bar();
 551       baz();
 552       mu.Unlock();
 553     }
 554
 555     void bar() {
 556       mu.Lock();       // WARNING!  Missing REQUIRES(!mu).
 557       // ...
 558       mu.Unlock();
 559     }
 560
 561     void baz() {
 562       bif();           // WARNING!  Missing REQUIRES(!mu).
 563     }
 564
 565     void bif() REQUIRES(!mu);
 566   };
 567
 568
 569 Negative requirements are an experimental feature which is off by default,
 570 because it will produce many warnings in existing code.  It can be enabled
 571 by passing ``-Wthread-safety-negative``.
 572
 573
 574 .. _faq:
 575
 576 Frequently Asked Questions
 577 ==========================
 578
 579 (Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
 580
 581 (A) Attributes are part of the formal interface of a function, and should
 582 always go in the header, where they are visible to anything that includes
 583 the header.  Attributes in the .cpp file are not visible outside of the
 584 immediate translation unit, which leads to false negatives and false positives.
 585
 586
 587 (Q) "*Mutex is not locked on every path through here?*"  What does that mean?
 588
 589 (A) See :ref:`conditional_locks`, below.
 590
 591
 592 .. _limitations:
 593
 594 Known Limitations
 595 =================
 596
 597 Lexical scope
 598 -------------
 599
 600 Thread safety attributes contain ordinary C++ expressions, and thus follow
 601 ordinary C++ scoping rules.  In particular, this means that mutexes and other
 602 capabilities must be declared before they can be used in an attribute.
 603 Use-before-declaration is okay within a single class, because attributes are
 604 parsed at the same time as method bodies. (C++ delays parsing of method bodies
 605 until the end of the class.)  However, use-before-declaration is not allowed
 606 between classes, as illustrated below.
 607
 608 .. code-block:: c++
 609
 610   class Foo;
 611
 612   class Bar {
 613     void bar(Foo* f) REQUIRES(f->mu);  // Error: mu undeclared.
 614   };
 615
 616   class Foo {
 617     Mutex mu;
 618   };
 619
 620
 621 Private Mutexes
 622 ---------------
 623
 624 Good software engineering practice dictates that mutexes should be private
 625 members, because the locking mechanism used by a thread-safe class is part of
 626 its internal implementation.  However, private mutexes can sometimes leak into
 627 the public interface of a class.
 628 Thread safety attributes follow normal C++ access restrictions, so if ``mu``
 629 is a private member of ``c``, then it is an error to write ``c.mu`` in an
 630 attribute.
 631
 632 One workaround is to (ab)use the ``RETURN_CAPABILITY`` attribute to provide a
 633 public *name* for a private mutex, without actually exposing the underlying
 634 mutex.  For example:
 635
 636 .. code-block:: c++
 637
 638   class MyClass {
 639   private:
 640     Mutex mu;
 641
 642   public:
 643     // For thread safety analysis only.  Does not actually return mu.
 644     Mutex* getMu() RETURN_CAPABILITY(mu) { return 0; }
 645
 646     void doSomething() REQUIRES(mu);
 647   };
 648
 649   void doSomethingTwice(MyClass& c) REQUIRES(c.getMu()) {
 650     // The analysis thinks that c.getMu() == c.mu
 651     c.doSomething();
 652     c.doSomething();
 653   }
 654
 655 In the above example, ``doSomethingTwice()`` is an external routine that
 656 requires ``c.mu`` to be locked, which cannot be declared directly because ``mu``
 657 is private.  This pattern is discouraged because it
 658 violates encapsulation, but it is sometimes necessary, especially when adding
 659 annotations to an existing code base.  The workaround is to define ``getMu()``
 660 as a fake getter method, which is provided only for the benefit of thread
 661 safety analysis.
 662
 663
 664 .. _conditional_locks:
 665
 666 No conditionally held locks.
 667 ----------------------------
 668
 669 The analysis must be able to determine whether a lock is held, or not held, at
 670 every program point.  Thus, sections of code where a lock *might be held* will
 671 generate spurious warnings (false positives).  For example:
 672
 673 .. code-block:: c++
 674
 675   void foo() {
 676     bool b = needsToLock();
 677     if (b) mu.Lock();
 678     ...  // Warning!  Mutex 'mu' is not held on every path through here.
 679     if (b) mu.Unlock();
 680   }
 681
 682
 683 No checking inside constructors and destructors.
 684 ------------------------------------------------
 685
 686 The analysis currently does not do any checking inside constructors or
 687 destructors.  In other words, every constructor and destructor is treated as
 688 if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``.
 689 The reason for this is that during initialization, only one thread typically
 690 has access to the object which is being initialized, and it is thus safe (and
 691 common practice) to initialize guarded members without acquiring any locks.
 692 The same is true of destructors.
 693
 694 Ideally, the analysis would allow initialization of guarded members inside the
 695 object being initialized or destroyed, while still enforcing the usual access
 696 restrictions on everything else.  However, this is difficult to enforce in
 697 practice, because in complex pointer-based data structures, it is hard to
 698 determine what data is owned by the enclosing object.
 699
 700 No inlining.
 701 ------------
 702
 703 Thread safety analysis is strictly intra-procedural, just like ordinary type
 704 checking.  It relies only on the declared attributes of a function, and will
 705 not attempt to inline any method calls.  As a result, code such as the
 706 following will not work:
 707
 708 .. code-block:: c++
 709
 710   template<class T>
 711   class AutoCleanup {
 712     T* object;
 713     void (T::*mp)();
 714
 715   public:
 716     AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
 717     ~AutoCleanup() { (object->*mp)(); }
 718   };
 719
 720   Mutex mu;
 721   void foo() {
 722     mu.Lock();
 723     AutoCleanup<Mutex>(&mu, &Mutex::Unlock);
 724     // ...
 725   }  // Warning, mu is not unlocked.
 726
 727 In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so
 728 the warning is bogus.  However,
 729 thread safety analysis cannot see the unlock, because it does not attempt to
 730 inline the destructor.  Moreover, there is no way to annotate the destructor,
 731 because the destructor is calling a function that is not statically known.
 732 This pattern is simply not supported.
 733
 734
 735 No alias analysis.
 736 ------------------
 737
 738 The analysis currently does not track pointer aliases.  Thus, there can be
 739 false positives if two pointers both point to the same mutex.
 740
 741
 742 .. code-block:: c++
 743
 744   class MutexUnlocker {
 745     Mutex* mu;
 746
 747   public:
 748     MutexUnlocker(Mutex* m) RELEASE(m) : mu(m)  { mu->Unlock(); }
 749     ~MutexUnlocker() ACQUIRE(mu) { mu->Lock(); }
 750   };
 751
 752   Mutex mutex;
 753   void test() REQUIRES(mutex) {
 754     {
 755       MutexUnlocker munl(&mutex);  // unlocks mutex
 756       doSomeIO();
 757     }                              // Warning: locks munl.mu
 758   }
 759
 760 The MutexUnlocker class is intended to be the dual of the MutexLocker class,
 761 defined in :ref:`mutexheader`.  However, it doesn't work because the analysis
 762 doesn't know that munl.mu == mutex.  The SCOPED_CAPABILITY attribute handles
 763 aliasing for MutexLocker, but does so only for that particular pattern.
 764
 765
 766 ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
 767 -------------------------------------------------------------------------
 768
 769 To be fixed in a future update.
 770
 771
 772 .. _mutexheader:
 773
 774 mutex.h
 775 =======
 776
 777 Thread safety analysis can be used with any threading library, but it does
 778 require that the threading API be wrapped in classes and methods which have the
 779 appropriate annotations.  The following code provides ``mutex.h`` as an example;
 780 these methods should be filled in to call the appropriate underlying
 781 implementation.
 782
 783
 784 .. code-block:: c++
 785
 786
 787   #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
 788   #define THREAD_SAFETY_ANALYSIS_MUTEX_H
 789
 790   // Enable thread safety attributes only with clang.
 791   // The attributes can be safely erased when compiling with other compilers.
 792   #if defined(__clang__) && (!defined(SWIG))
 793   #define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
 794   #else
 795   #define THREAD_ANNOTATION_ATTRIBUTE__(x)   // no-op
 796   #endif
 797
 798   #define CAPABILITY(x) \
 799     THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
 800
 801   #define SCOPED_CAPABILITY \
 802     THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
 803
 804   #define GUARDED_BY(x) \
 805     THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
 806
 807   #define PT_GUARDED_BY(x) \
 808     THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
 809
 810   #define ACQUIRED_BEFORE(...) \
 811     THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
 812
 813   #define ACQUIRED_AFTER(...) \
 814     THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
 815
 816   #define REQUIRES(...) \
 817     THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))
 818
 819   #define REQUIRES_SHARED(...) \
 820     THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))
 821
 822   #define ACQUIRE(...) \
 823     THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))
 824
 825   #define ACQUIRE_SHARED(...) \
 826     THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
 827
 828   #define RELEASE(...) \
 829     THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
 830
 831   #define RELEASE_SHARED(...) \
 832     THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
 833
 834   #define RELEASE_GENERIC(...) \
 835     THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
 836
 837   #define TRY_ACQUIRE(...) \
 838     THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
 839
 840   #define TRY_ACQUIRE_SHARED(...) \
 841     THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
 842
 843   #define EXCLUDES(...) \
 844     THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
 845
 846   #define ASSERT_CAPABILITY(x) \
 847     THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
 848
 849   #define ASSERT_SHARED_CAPABILITY(x) \
 850     THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
 851
 852   #define RETURN_CAPABILITY(x) \
 853     THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
 854
 855   #define NO_THREAD_SAFETY_ANALYSIS \
 856     THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 857
 858
 859   // Defines an annotated interface for mutexes.
 860   // These methods can be implemented to use any internal mutex implementation.
 861   class CAPABILITY("mutex") Mutex {
 862   public:
 863     // Acquire/lock this mutex exclusively.  Only one thread can have exclusive
 864     // access at any one time.  Write operations to guarded data require an
 865     // exclusive lock.
 866     void Lock() ACQUIRE();
 867
 868     // Acquire/lock this mutex for read operations, which require only a shared
 869     // lock.  This assumes a multiple-reader, single writer semantics.  Multiple
 870     // threads may acquire the mutex simultaneously as readers, but a writer
 871     // must wait for all of them to release the mutex before it can acquire it
 872     // exclusively.
 873     void ReaderLock() ACQUIRE_SHARED();
 874
 875     // Release/unlock an exclusive mutex.
 876     void Unlock() RELEASE();
 877
 878     // Release/unlock a shared mutex.
 879     void ReaderUnlock() RELEASE_SHARED();
 880
 881     // Generic unlock, can unlock exclusive and shared mutexes.
 882     void GenericUnlock() RELEASE_GENERIC();
 883
 884     // Try to acquire the mutex.  Returns true on success, and false on failure.
 885     bool TryLock() TRY_ACQUIRE(true);
 886
 887     // Try to acquire the mutex for read operations.
 888     bool ReaderTryLock() TRY_ACQUIRE_SHARED(true);
 889
 890     // Assert that this mutex is currently held by the calling thread.
 891     void AssertHeld() ASSERT_CAPABILITY(this);
 892
 893     // Assert that is mutex is currently held for read operations.
 894     void AssertReaderHeld() ASSERT_SHARED_CAPABILITY(this);
 895
 896     // For negative capabilities.
 897     const Mutex& operator!() const { return *this; }
 898   };
 899
 900   // Tag types for selecting a constructor.
 901   struct adopt_lock_t {} inline constexpr adopt_lock = {};
 902   struct defer_lock_t {} inline constexpr defer_lock = {};
 903   struct shared_lock_t {} inline constexpr shared_lock = {};
 904
 905   // MutexLocker is an RAII class that acquires a mutex in its constructor, and
 906   // releases it in its destructor.
 907   class SCOPED_CAPABILITY MutexLocker {
 908   private:
 909     Mutex* mut;
 910     bool locked;
 911
 912   public:
 913     // Acquire mu, implicitly acquire *this and associate it with mu.
 914     MutexLocker(Mutex *mu) ACQUIRE(mu) : mut(mu), locked(true) {
 915       mu->Lock();
 916     }
 917
 918     // Assume mu is held, implicitly acquire *this and associate it with mu.
 919     MutexLocker(Mutex *mu, adopt_lock_t) REQUIRES(mu) : mut(mu), locked(true) {}
 920
 921     // Acquire mu in shared mode, implicitly acquire *this and associate it with mu.
 922     MutexLocker(Mutex *mu, shared_lock_t) ACQUIRE_SHARED(mu) : mut(mu), locked(true) {
 923       mu->ReaderLock();
 924     }
 925
 926     // Assume mu is held in shared mode, implicitly acquire *this and associate it with mu.
 927     MutexLocker(Mutex *mu, adopt_lock_t, shared_lock_t) REQUIRES_SHARED(mu)
 928       : mut(mu), locked(true) {}
 929
 930     // Assume mu is not held, implicitly acquire *this and associate it with mu.
 931     MutexLocker(Mutex *mu, defer_lock_t) EXCLUDES(mu) : mut(mu), locked(false) {}
 932
 933     // Release *this and all associated mutexes, if they are still held.
 934     // There is no warning if the scope was already unlocked before.
 935     ~MutexLocker() RELEASE() {
 936       if (locked)
 937         mut->GenericUnlock();
 938     }
 939
 940     // Acquire all associated mutexes exclusively.
 941     void Lock() ACQUIRE() {
 942       mut->Lock();
 943       locked = true;
 944     }
 945
 946     // Try to acquire all associated mutexes exclusively.
 947     bool TryLock() TRY_ACQUIRE(true) {
 948       return locked = mut->TryLock();
 949     }
 950
 951     // Acquire all associated mutexes in shared mode.
 952     void ReaderLock() ACQUIRE_SHARED() {
 953       mut->ReaderLock();
 954       locked = true;
 955     }
 956
 957     // Try to acquire all associated mutexes in shared mode.
 958     bool ReaderTryLock() TRY_ACQUIRE_SHARED(true) {
 959       return locked = mut->ReaderTryLock();
 960     }
 961
 962     // Release all associated mutexes. Warn on double unlock.
 963     void Unlock() RELEASE() {
 964       mut->Unlock();
 965       locked = false;
 966     }
 967
 968     // Release all associated mutexes. Warn on double unlock.
 969     void ReaderUnlock() RELEASE() {
 970       mut->ReaderUnlock();
 971       locked = false;
 972     }
 973   };
 974
 975
 976   #ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
 977   // The original version of thread safety analysis the following attribute
 978   // definitions.  These use a lock-based terminology.  They are still in use
 979   // by existing thread safety code, and will continue to be supported.
 980
 981   // Deprecated.
 982   #define PT_GUARDED_VAR \
 983     THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_var)
 984
 985   // Deprecated.
 986   #define GUARDED_VAR \
 987     THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)
 988
 989   // Replaced by REQUIRES
 990   #define EXCLUSIVE_LOCKS_REQUIRED(...) \
 991     THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
 992
 993   // Replaced by REQUIRES_SHARED
 994   #define SHARED_LOCKS_REQUIRED(...) \
 995     THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
 996
 997   // Replaced by CAPABILITY
 998   #define LOCKABLE \
 999     THREAD_ANNOTATION_ATTRIBUTE__(lockable)
1000
1001   // Replaced by SCOPED_CAPABILITY
1002   #define SCOPED_LOCKABLE \
1003     THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
1004
1005   // Replaced by ACQUIRE
1006   #define EXCLUSIVE_LOCK_FUNCTION(...) \
1007     THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
1008
1009   // Replaced by ACQUIRE_SHARED
1010   #define SHARED_LOCK_FUNCTION(...) \
1011     THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
1012
1013   // Replaced by RELEASE and RELEASE_SHARED
1014   #define UNLOCK_FUNCTION(...) \
1015     THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
1016
1017   // Replaced by TRY_ACQUIRE
1018   #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
1019     THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
1020
1021   // Replaced by TRY_ACQUIRE_SHARED
1022   #define SHARED_TRYLOCK_FUNCTION(...) \
1023     THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
1024
1025   // Replaced by ASSERT_CAPABILITY
1026   #define ASSERT_EXCLUSIVE_LOCK(...) \
1027     THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
1028
1029   // Replaced by ASSERT_SHARED_CAPABILITY
1030   #define ASSERT_SHARED_LOCK(...) \
1031     THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
1032
1033   // Replaced by EXCLUDE_CAPABILITY.
1034   #define LOCKS_EXCLUDED(...) \
1035     THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
1036
1037   // Replaced by RETURN_CAPABILITY
1038   #define LOCK_RETURNED(x) \
1039     THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
1040
1041   #endif  // USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
1042
1043   #endif  // THREAD_SAFETY_ANALYSIS_MUTEX_H
1044