Getting Started¶

#include "mutex.h"

class BankAccount {
private:
  Mutex mu;
  int   balance GUARDED_BY(mu);

  void depositImpl(int amount) {
    balance += amount;       // WARNING! Cannot write balance without locking mu.
  }

  void withdrawImpl(int amount) EXCLUSIVE_LOCKS_REQUIRED(mu) {
    balance -= amount;       // OK. Caller must have locked mu.
  }

public:
  void withdraw(int amount) {
    mu.Lock();
    withdrawImpl(amount);    // OK.  We've locked mu.
  }                          // WARNING!  Failed to unlock mu.

  void transferFrom(BankAccount& b, int amount) {
    mu.Lock();
    b.withdrawImpl(amount);  // WARNING!  Calling withdrawImpl() requires locking b.mu.
    depositImpl(amount);     // OK.  depositImpl() has no requirements.
    mu.Unlock();
  }
};

This example demonstrates the basic concepts behind the analysis. The GUARDED_BY attribute declares that a thread must lock mu before it can read or write to balance, thus ensuring that the increment and decrement operations are atomic. Similarly, EXCLUSIVE_LOCKS_REQUIRED declares that the calling thread must lock mu before calling withdrawImpl. Because the caller is assumed to have locked mu, it is safe to modify balance within the body of the method.

The depositImpl() method does not have EXCLUSIVE_LOCKS_REQUIRED, so the analysis issues a warning. Thread safety analysis is not inter-procedural, so caller requirements must be explicitly declared. There is also a warning in transferFrom(), because although the method locks this->mu, it does not lock b.mu. The analysis understands that these are two separate mutexes, in two different objects.

Finally, there is a warning in the withdraw() method, because it fails to unlock mu. Every lock must have a corresponding unlock, and the analysis will detect both double locks, and double unlocks. A function is allowed to acquire a lock without releasing it, (or vice versa), but it must be annotated as such (using LOCK/UNLOCK_FUNCTION).

Running The Analysis¶

To run the analysis, simply compile with the -Wthread-safety flag, e.g.

clang -c -Wthread-safety example.cpp

Note that this example assumes the presence of a suitably annotated mutex.h that declares which methods perform locking, unlocking, and so on.

GUARDED_BY(c) and PT_GUARDED_BY(c)¶

GUARDED_BY is an attribute on data members, which declares that the data member is protected by the given capability. Read operations on the data require shared access, while write operations require exclusive access.

PT_GUARDED_BY is similar, but is intended for use on pointers and smart pointers. There is no constraint on the data member itself, but the data that it points to is protected by the given capability.

Mutex mu;
int *p1            GUARDED_BY(mu);
int *p2            PT_GUARDED_BY(mu);
unique_ptr<int> p3 PT_GUARDED_BY(mu);

void test() {
  p1 = 0;             // Warning!

  p2 = new int;       // OK.
  *p2 = 42;           // Warning!

  p3.reset(new int);  // OK.
  *p3 = 42;           // Warning!
}

EXCLUSIVE_LOCKS_REQUIRED(...), SHARED_LOCKS_REQUIRED(...)¶

EXCLUSIVE_LOCKS_REQUIRED is an attribute on functions or methods, which declares that the calling thread must have exclusive access to the given capabilities. More than one capability may be specified. The capabilities must be held on entry to the function, and must still be held on exit.

SHARED_LOCKS_REQUIRED is similar, but requires only shared access.

Mutex mu1, mu2;
int a GUARDED_BY(mu1);
int b GUARDED_BY(mu2);

void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) {
  a = 0;
  b = 0;
}

void test() {
  mu1.Lock();
  foo();         // Warning!  Requires mu2.
  mu1.Unlock();
}

EXCLUSIVE_LOCK_FUNCTION(...), SHARED_LOCK_FUNCTION(...), UNLOCK_FUNCTION(...)¶

EXCLUSIVE_LOCK_FUNCTION is an attribute on functions or methods, which declares that the function acquires a capability, but does not release it. The caller must not hold the given capability on entry, and it will hold the capability on exit. SHARED_LOCK_FUNCTION is similar.

UNLOCK_FUNCTION declares that the function releases the given capability. The caller must hold the capability on entry, and will no longer hold it on exit. It does not matter whether the given capability is shared or exclusive.

Mutex mu;
MyClass myObject GUARDED_BY(mu);

void lockAndInit() EXCLUSIVE_LOCK_FUNCTION(mu) {
  mu.Lock();
  myObject.init();
}

void cleanupAndUnlock() UNLOCK_FUNCTION(mu) {
  myObject.cleanup();
}  // Warning!  Need to unlock mu.

void test() {
  lockAndInit();
  myObject.doSomething();
  cleanupAndUnlock();
  myObject.doSomething();  // Warning, mu is not locked.
}

If no argument is passed to (UN)LOCK_FUNCTION, then the argument is assumed to be this, and the analysis will not check the body of the function. This pattern is intended for use by classes which hide locking details behind an abstract interface. E.g.

template <class T>
class LOCKABLE Container {
private:
  Mutex mu;
  T* data;

public:
  // Hide mu from public interface.
  void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu.Lock(); }
  void Unlock() UNLOCK_FUNCTION() { mu.Unlock(); }

  T& getElem(int i) { return data[i]; }
};

void test() {
  Container<int> c;
  c.Lock();
  int i = c.getElem(0);
  c.Unlock();
}

LOCKS_EXCLUDED(...)¶

LOCKS_EXCLUDED is an attribute on functions or methods, which declares that the caller must not hold the given capabilities. This annotation is used to prevent deadlock. Many mutex implementations are not re-entrant, so deadlock can occur if the function in question acquires the mutex a second time.

Mutex mu;
int a GUARDED_BY(mu);

void clear() LOCKS_EXCLUDED(mu) {
  mu.Lock();
  a = 0;
  mu.Unlock();
}

void reset() {
  mu.Lock();
  clear();     // Warning!  Caller cannot hold 'mu'.
  mu.Unlock();
}

Unlike LOCKS_REQUIRED, LOCKS_EXCLUDED is optional. The analysis will not issue a warning if the attribute is missing. See Known Limitations.

NO_THREAD_SAFETY_ANALYSIS¶

NO_THREAD_SAFETY_ANALYSIS is an attribute on functions or methods, which turns off thread safety checking for that method. It provides an escape hatch for functions which are either (1) deliberately thread-unsafe, or (2) are thread-safe, but too complicated for the analysis to understand. Reasons for (2) will be described in the Known Limitations, below.

class Counter {
  Mutex mu;
  int a GUARDED_BY(mu);

  void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
};

LOCK_RETURNED(c)¶

LOCK_RETURNED is an attribute on functions or methods, which declares that the function returns a reference to the given capability. It is used to annotate getter methods that return mutexes.

class MyClass {
private:
  Mutex mu;
  int a GUARDED_BY(mu);

public:
  Mutex* getMu() LOCK_RETURNED(mu) { return μ }

  // analysis knows that getMu() == mu
  void clear() EXCLUSIVE_LOCKS_REQUIRED(getMu()) { a = 0; }
};

ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)¶

ACQUIRED_BEFORE and ACQUIRED_AFTER are attributes on member declarations, specifically declarations of mutexes or other capabilities. These declarations enforce a particular order in which the mutexes must be acquired, in order to prevent deadlock.

Mutex m1;
Mutex m2 ACQUIRED_AFTER(m1);

// Alternative declaration
// Mutex m2;
// Mutex m1 ACQUIRED_BEFORE(m2);

void foo() {
  m2.Lock();
  m1.Lock();  // Warning!  m2 must be acquired after m1.
  m1.Unlock();
  m2.Unlock();
}

LOCKABLE¶

LOCKABLE is an attribute on classes, which specifies that objects of the class can be used as a capability. See the Container example given above, or the Mutex class in mutex.h.

SCOPED_LOCKABLE¶

SCOPED_LOCKABLE is an attribute on classes that implement RAII-style locking, in which a capability is acquired in the constructor, and released in the destructor. Such classes require special handling because the constructor and destructor refer to the capability via different names; see the MutexLocker class in mutex.h, below.

EXCLUSIVE_TRYLOCK_FUNCTION(<bool>, ...), SHARED_TRYLOCK_FUNCTION(<bool>, ...)¶

These are attributes on a function or method that tries to acquire the given capability, and returns a boolean value indicating success or failure. The first argument must be true or false, to specify which return value indicates success, and the remaining arguments are interpreted in the same way as (UN)LOCK_FUNCTION. See mutex.h, below, for example uses.

ASSERT_EXCLUSIVE_LOCK(...) and ASSERT_SHARED_LOCK(...)¶

These are attributes on a function or method that does a run-time test to see whether the calling thread holds the given capability. The function is assumed to fail (no return) if the capability is not held. See mutex.h, below, for example uses.

GUARDED_VAR and PT_GUARDED_VAR¶

Use of these attributes has been deprecated.

Warning flags¶

• -Wthread-safety: Umbrella flag which turns on the following three:
  • -Wthread-safety-attributes: Sanity checks on attribute syntax.
  • -Wthread-safety-analysis: The core analysis.
  • -Wthread-safety-precise: Requires that mutex expressions match precisely. This warning can be disabled for code which has a lot of aliases.

When new features and checks are added to the analysis, they can often introduce additional warnings. Those warnings are initially released as beta warnings for a period of time, after which they are migrated to the standard analysis.

• -Wthread-safety-beta: New features. Off by default.

Lexical scope¶

Thread safety attributes contain ordinary C++ expressions, and thus follow ordinary C++ scoping rules. In particular, this means that mutexes and other capabilities must be declared before they can be used in an attribute. Use-before-declaration is okay within a single class, because attributes are parsed at the same time as method bodies. (C++ delays parsing of method bodies until the end of the class.) However, use-before-declaration is not allowed between classes, as illustrated below.

class Foo;

class Bar {
  void bar(Foo* f) EXCLUSIVE_LOCKS_REQUIRED(f->mu);  // Error: mu undeclared.
};

class Foo {
  Mutex mu;
};

Private Mutexes¶

Good software engineering practice dictates that mutexes should be private members, because the locking mechanism used by a thread-safe class is part of its internal implementation. However, private mutexes can sometimes leak into the public interface of a class. Thread safety attributes follow normal C++ access restrictions, so if mu is a private member of c, then it is an error to write c.mu in an attribute.

One workround is to (ab)use the LOCK_RETURNED attribute to provide a public name for a private mutex, without actually exposing the underlying mutex. For example:

class MyClass {
private:
  Mutex mu;

public:
  // For thread safety analysis only.  Does not actually return mu.
  Mutex* getMu() LOCK_RETURNED(mu) { return 0; }

  void doSomething() EXCLUSIVE_LOCKS_REQUIRED(mu);
};

void doSomethingTwice(MyClass& c) EXCLUSIVE_LOCKS_REQUIRED(c.getMu()) {
  // The analysis thinks that c.getMu() == c.mu
  c.doSomething();
  c.doSomething();
}

In the above example, doSomethingTwice() is an external routine that requires c.mu to be locked, which cannot be declared directly because mu is private. This pattern is discouraged because it violates encapsulation, but it is sometimes necessary, especially when adding annotations to an existing code base. The workaround is to define getMu() as a fake getter method, which is provided only for the benefit of thread safety analysis.

False negatives on pass by reference.¶

The current version of the analysis only checks operations which refer to guarded data members directly by name. If the data members are accessed indirectly, via a pointer or reference, then no warning is generated. Thus, no warnings will be generated for the following code:

Mutex mu;
int a GUARDED_BY(mu);

void clear(int& ra) { ra = 0; }

void test() {
  int *p = &a;
  *p = 0;       // No warning.  *p is an alias to a.

  clear(a);     // No warning.  'a' is passed by reference.
}

This issue is by far the biggest source of false negatives in the current version of the analysis. At a fundamental level, the false negatives are caused by the fact that annotations are attached to data members, rather than types. The type of &a should really be int GUARDED_BY(mu)*, rather than int*, and the statement p = &a should thus generate a type error. However, attaching attributes to types would be an invasive change to the C++ type system, with potential ramifications with respect to template instantation, function overloading, and so on. Thus, a complete solution to this issue is simply not feasible.

Future versions of the analysis will include better support for pointer alias analysis, along with limited checking of guarded types, in order to reduce the number of false negatives.

No conditionally held locks.¶

The analysis must be able to determine whether a lock is held, or not held, at every program point. Thus, sections of code where a lock might be held will generate spurious warnings (false positives). For example:

void foo() {
  bool b = needsToLock();
  if (b) mu.Lock();
  ...  // Warning!  Mutex 'mu' is not held on every path through here.
  if (b) mu.Unlock();
}

No checking inside constructors and destructors.¶

The analysis currently does not do any checking inside constructors or destructors. In other words, every constructor and destructor is treated as if it was annotated with NO_THREAD_SAFETY_ANALYSIS. The reason for this is that during initialization, only one thread typically has access to the object which is being initialized, and it is thus safe (and common practice) to initialize guarded members without acquiring any locks. The same is true of destructors.

Ideally, the analysis would allow initialization of guarded members inside the object being initialized or destroyed, while still enforcing the usual access restrictions on everything else. However, this is difficult to enforce in practice, because in complex pointer-based data structures, it is hard to determine what data is “owned by” the enclosing object.

No inlining.¶

Thread safety analysis is strictly intra-procedural, just like ordinary type checking. It relies only on the declared attributes of a function, and will not attempt to “step inside”, or inline any method calls. As a result, code such as the following will not work:

template<class T>
class AutoCleanup {
  T* object;
  void (T::*mp)();

public:
  AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
  ~AutoCleanup() { (object->*mp)(); }
};

Mutex mu;
void foo() {
  mu.Lock();
  AutoCleanup<Mutex>(&mu, &Mutex::Unlock);
  ...
}  // Warning, mu is not unlocked.

In this case, the destructor of Autocleanup calls mu.Unlock(), so the warning is bogus. However, thread safety analysis cannot see the unlock, because it does not attempt to inline the destructor. Moreover, there is no way to annotate the destructor, because the destructor is calling a function that is not statically known. This pattern is simply not supported.

LOCKS_EXCLUDED is not transitive.¶

A function which calls a method marked with LOCKS_EXCLUDED is not required to put LOCKS_EXCLUDED in its own interface. LOCKS_EXCLUDED behaves differently from LOCKS_REQUIRED in this respect, and it can result in false negatives:

class Foo {
  Mutex mu;

  void foo() {
    mu.Lock();
    bar();                // No warning
    mu.Unlock();
  }

  void bar() { baz(); }   // No warning.  (Should have LOCKS_EXCLUDED(mu).)

  void baz() LOCKS_EXCLUDED(mu);
};

The lack of transitivity is due to the fact that LOCKS_EXCLUDED can easily break encapsulation; it would be a bad idea to require functions to list the names private locks which happen to be acquired internally.

No alias analysis.¶

The analysis currently does not track pointer aliases. Thus, there can be false positives if two pointers both point to the same mutex.

class MutexUnlocker {
  Mutex* mu;

public:
  MutexUnlocker(Mutex* m) UNLOCK_FUNCTION(m) : mu(m)  { mu->Unlock(); }
  ~MutexUnlocker() EXCLUSIVE_LOCK_FUNCTION(mu) { mu->Lock(); }
};

Mutex mutex;
void test() EXCLUSIVE_LOCKS_REQUIRED(mutex) {
  {
    MutexUnlocker munl(&mutex);  // unlocks mutex
    doSomeIO();
  }                              // Warning: locks munl.mu
}

The MutexUnlocker class is intended to be the dual of the MutexLocker class, defined in mutex.h. However, it doesn’t work because the analysis doesn’t know that munl.mu == mutex. The SCOPED_LOCKABLE attribute handles aliasing

ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.¶

To be fixed in a future update.