1045 lines
34 KiB
ReStructuredText
1045 lines
34 KiB
ReStructuredText
|
|
======================
|
|
Thread Safety Analysis
|
|
======================
|
|
|
|
Introduction
|
|
============
|
|
|
|
Clang Thread Safety Analysis is a C++ language extension which warns about
|
|
potential race conditions in code. The analysis is completely static (i.e.
|
|
compile-time); there is no run-time overhead. The analysis is still
|
|
under active development, but it is mature enough to be deployed in an
|
|
industrial setting. It is being developed by Google, in collaboration with
|
|
CERT/SEI, and is used extensively in Google's internal code base.
|
|
|
|
Thread safety analysis works very much like a type system for multi-threaded
|
|
programs. In addition to declaring the *type* of data (e.g. ``int``, ``float``,
|
|
etc.), the programmer can (optionally) declare how access to that data is
|
|
controlled in a multi-threaded environment. For example, if ``foo`` is
|
|
*guarded by* the mutex ``mu``, then the analysis will issue a warning whenever
|
|
a piece of code reads or writes to ``foo`` without first locking ``mu``.
|
|
Similarly, if there are particular routines that should only be called by
|
|
the GUI thread, then the analysis will warn if other threads call those
|
|
routines.
|
|
|
|
Getting Started
|
|
----------------
|
|
|
|
.. code-block:: c++
|
|
|
|
#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) REQUIRES(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, ``REQUIRES`` 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 ``REQUIRES``, 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 ``ACQUIRE``/``RELEASE``).
|
|
|
|
|
|
Running The Analysis
|
|
--------------------
|
|
|
|
To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g.
|
|
|
|
.. code-block:: bash
|
|
|
|
clang -c -Wthread-safety example.cpp
|
|
|
|
Note that this example assumes the presence of a suitably annotated
|
|
:ref:`mutexheader` that declares which methods perform locking,
|
|
unlocking, and so on.
|
|
|
|
|
|
Basic Concepts: Capabilities
|
|
============================
|
|
|
|
Thread safety analysis provides a way of protecting *resources* with
|
|
*capabilities*. A resource is either a data member, or a function/method
|
|
that provides access to some underlying resource. The analysis ensures that
|
|
the calling thread cannot access the *resource* (i.e. call the function, or
|
|
read/write the data) unless it has the *capability* to do so.
|
|
|
|
Capabilities are associated with named C++ objects which declare specific
|
|
methods to acquire and release the capability. The name of the object serves
|
|
to identify the capability. The most common example is a mutex. For example,
|
|
if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread
|
|
to acquire the capability to access data that is protected by ``mu``. Similarly,
|
|
calling ``mu.Unlock()`` releases that capability.
|
|
|
|
A thread may hold a capability either *exclusively* or *shared*. An exclusive
|
|
capability can be held by only one thread at a time, while a shared capability
|
|
can be held by many threads at the same time. This mechanism enforces a
|
|
multiple-reader, single-writer pattern. Write operations to protected data
|
|
require exclusive access, while read operations require only shared access.
|
|
|
|
At any given moment during program execution, a thread holds a specific set of
|
|
capabilities (e.g. the set of mutexes that it has locked.) These act like keys
|
|
or tokens that allow the thread to access a given resource. Just like physical
|
|
security keys, a thread cannot make copy of a capability, nor can it destroy
|
|
one. A thread can only release a capability to another thread, or acquire one
|
|
from another thread. The annotations are deliberately agnostic about the
|
|
exact mechanism used to acquire and release capabilities; it assumes that the
|
|
underlying implementation (e.g. the Mutex implementation) does the handoff in
|
|
an appropriate manner.
|
|
|
|
The set of capabilities that are actually held by a given thread at a given
|
|
point in program execution is a run-time concept. The static analysis works
|
|
by calculating an approximation of that set, called the *capability
|
|
environment*. The capability environment is calculated for every program point,
|
|
and describes the set of capabilities that are statically known to be held, or
|
|
not held, at that particular point. This environment is a conservative
|
|
approximation of the full set of capabilities that will actually held by a
|
|
thread at run-time.
|
|
|
|
|
|
Reference Guide
|
|
===============
|
|
|
|
The thread safety analysis uses attributes to declare threading constraints.
|
|
Attributes must be attached to named declarations, such as classes, methods,
|
|
and data members. Users are *strongly advised* to define macros for the various
|
|
attributes; example definitions can be found in :ref:`mutexheader`, below.
|
|
The following documentation assumes the use of macros.
|
|
|
|
The attributes only control assumptions made by thread safety analysis and the
|
|
warnings it issues. They don't affect generated code or behavior at run-time.
|
|
|
|
For historical reasons, prior versions of thread safety used macro names that
|
|
were very lock-centric. These macros have since been renamed to fit a more
|
|
general capability model. The prior names are still in use, and will be
|
|
mentioned under the tag *previously* where appropriate.
|
|
|
|
|
|
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.
|
|
|
|
.. code-block:: c++
|
|
|
|
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 = 42; // Warning!
|
|
p2 = new int; // OK.
|
|
|
|
*p3 = 42; // Warning!
|
|
p3.reset(new int); // OK.
|
|
}
|
|
|
|
|
|
REQUIRES(...), REQUIRES_SHARED(...)
|
|
-----------------------------------
|
|
|
|
*Previously*: ``EXCLUSIVE_LOCKS_REQUIRED``, ``SHARED_LOCKS_REQUIRED``
|
|
|
|
``REQUIRES`` 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*.
|
|
|
|
``REQUIRES_SHARED`` is similar, but requires only shared access.
|
|
|
|
.. code-block:: c++
|
|
|
|
Mutex mu1, mu2;
|
|
int a GUARDED_BY(mu1);
|
|
int b GUARDED_BY(mu2);
|
|
|
|
void foo() REQUIRES(mu1, mu2) {
|
|
a = 0;
|
|
b = 0;
|
|
}
|
|
|
|
void test() {
|
|
mu1.Lock();
|
|
foo(); // Warning! Requires mu2.
|
|
mu1.Unlock();
|
|
}
|
|
|
|
|
|
ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...), RELEASE_GENERIC(...)
|
|
------------------------------------------------------------------------------------------
|
|
|
|
*Previously*: ``EXCLUSIVE_LOCK_FUNCTION``, ``SHARED_LOCK_FUNCTION``,
|
|
``UNLOCK_FUNCTION``
|
|
|
|
``ACQUIRE`` and ``ACQUIRE_SHARED`` are attributes on functions or methods
|
|
declaring that the function acquires a capability, but does not release it.
|
|
The given capability must not be held on entry, and will be held on exit
|
|
(exclusively for ``ACQUIRE``, shared for ``ACQUIRE_SHARED``).
|
|
|
|
``RELEASE``, ``RELEASE_SHARED``, and ``RELEASE_GENERIC`` declare that the
|
|
function releases the given capability. The capability must be held on entry
|
|
(exclusively for ``RELEASE``, shared for ``RELEASE_SHARED``, exclusively or
|
|
shared for ``RELEASE_GENERIC``), and will no longer be held on exit.
|
|
|
|
.. code-block:: c++
|
|
|
|
Mutex mu;
|
|
MyClass myObject GUARDED_BY(mu);
|
|
|
|
void lockAndInit() ACQUIRE(mu) {
|
|
mu.Lock();
|
|
myObject.init();
|
|
}
|
|
|
|
void cleanupAndUnlock() RELEASE(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 ``ACQUIRE`` or ``RELEASE``, 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. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
template <class T>
|
|
class CAPABILITY("mutex") Container {
|
|
private:
|
|
Mutex mu;
|
|
T* data;
|
|
|
|
public:
|
|
// Hide mu from public interface.
|
|
void Lock() ACQUIRE() { mu.Lock(); }
|
|
void Unlock() RELEASE() { mu.Unlock(); }
|
|
|
|
T& getElem(int i) { return data[i]; }
|
|
};
|
|
|
|
void test() {
|
|
Container<int> c;
|
|
c.Lock();
|
|
int i = c.getElem(0);
|
|
c.Unlock();
|
|
}
|
|
|
|
|
|
EXCLUDES(...)
|
|
-------------
|
|
|
|
*Previously*: ``LOCKS_EXCLUDED``
|
|
|
|
``EXCLUDES`` 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 acquires the mutex a second time.
|
|
|
|
.. code-block:: c++
|
|
|
|
Mutex mu;
|
|
int a GUARDED_BY(mu);
|
|
|
|
void clear() EXCLUDES(mu) {
|
|
mu.Lock();
|
|
a = 0;
|
|
mu.Unlock();
|
|
}
|
|
|
|
void reset() {
|
|
mu.Lock();
|
|
clear(); // Warning! Caller cannot hold 'mu'.
|
|
mu.Unlock();
|
|
}
|
|
|
|
Unlike ``REQUIRES``, ``EXCLUDES`` is optional. The analysis will not issue a
|
|
warning if the attribute is missing, which can lead to false negatives in some
|
|
cases. This issue is discussed further in :ref:`negative`.
|
|
|
|
|
|
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 :ref:`limitations`, below.
|
|
|
|
.. code-block:: c++
|
|
|
|
class Counter {
|
|
Mutex mu;
|
|
int a GUARDED_BY(mu);
|
|
|
|
void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
|
|
};
|
|
|
|
Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
|
|
interface of a function, and should thus be placed on the function definition
|
|
(in the ``.cc`` or ``.cpp`` file) rather than on the function declaration
|
|
(in the header).
|
|
|
|
|
|
RETURN_CAPABILITY(c)
|
|
--------------------
|
|
|
|
*Previously*: ``LOCK_RETURNED``
|
|
|
|
``RETURN_CAPABILITY`` 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.
|
|
|
|
.. code-block:: c++
|
|
|
|
class MyClass {
|
|
private:
|
|
Mutex mu;
|
|
int a GUARDED_BY(mu);
|
|
|
|
public:
|
|
Mutex* getMu() RETURN_CAPABILITY(mu) { return μ }
|
|
|
|
// analysis knows that getMu() == mu
|
|
void clear() REQUIRES(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.
|
|
|
|
.. code-block:: c++
|
|
|
|
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();
|
|
}
|
|
|
|
|
|
CAPABILITY(<string>)
|
|
--------------------
|
|
|
|
*Previously*: ``LOCKABLE``
|
|
|
|
``CAPABILITY`` is an attribute on classes, which specifies that objects of the
|
|
class can be used as a capability. The string argument specifies the kind of
|
|
capability in error messages, e.g. ``"mutex"``. See the ``Container`` example
|
|
given above, or the ``Mutex`` class in :ref:`mutexheader`.
|
|
|
|
|
|
SCOPED_CAPABILITY
|
|
-----------------
|
|
|
|
*Previously*: ``SCOPED_LOCKABLE``
|
|
|
|
``SCOPED_CAPABILITY`` 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 :ref:`mutexheader`, below.
|
|
|
|
Scoped capabilities are treated as capabilities that are implicitly acquired
|
|
on construction and released on destruction. They are associated with
|
|
the set of (regular) capabilities named in thread safety attributes on the
|
|
constructor. Acquire-type attributes on other member functions are treated as
|
|
applying to that set of associated capabilities, while ``RELEASE`` implies that
|
|
a function releases all associated capabilities in whatever mode they're held.
|
|
|
|
|
|
TRY_ACQUIRE(<bool>, ...), TRY_ACQUIRE_SHARED(<bool>, ...)
|
|
---------------------------------------------------------
|
|
|
|
*Previously:* ``EXCLUSIVE_TRYLOCK_FUNCTION``, ``SHARED_TRYLOCK_FUNCTION``
|
|
|
|
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 ``ACQUIRE``. See :ref:`mutexheader`, below, for example uses.
|
|
|
|
Because the analysis doesn't support conditional locking, a capability is
|
|
treated as acquired after the first branch on the return value of a try-acquire
|
|
function.
|
|
|
|
.. code-block:: c++
|
|
|
|
Mutex mu;
|
|
int a GUARDED_BY(mu);
|
|
|
|
void foo() {
|
|
bool success = mu.TryLock();
|
|
a = 0; // Warning, mu is not locked.
|
|
if (success) {
|
|
a = 0; // Ok.
|
|
mu.Unlock();
|
|
} else {
|
|
a = 0; // Warning, mu is not locked.
|
|
}
|
|
}
|
|
|
|
|
|
ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)
|
|
--------------------------------------------------------
|
|
|
|
*Previously:* ``ASSERT_EXCLUSIVE_LOCK``, ``ASSERT_SHARED_LOCK``
|
|
|
|
These are attributes on a function or method which asserts the calling thread
|
|
already holds the given capability, for example by performing a run-time test
|
|
and terminating if the capability is not held. Presence of this annotation
|
|
causes the analysis to assume the capability is held after calls to the
|
|
annotated function. See :ref:`mutexheader`, 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.
|
|
+ ``-Wthread-safety-reference``: Checks when guarded members are passed by reference.
|
|
|
|
|
|
:ref:`negative` are an experimental feature, which are enabled with:
|
|
|
|
* ``-Wthread-safety-negative``: Negative capabilities. Off by default.
|
|
|
|
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 into the standard analysis.
|
|
|
|
* ``-Wthread-safety-beta``: New features. Off by default.
|
|
|
|
|
|
.. _negative:
|
|
|
|
Negative Capabilities
|
|
=====================
|
|
|
|
Thread Safety Analysis is designed to prevent both race conditions and
|
|
deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by
|
|
ensuring that a capability is held before reading or writing to guarded data,
|
|
and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
|
|
*not* held.
|
|
|
|
However, EXCLUDES is an optional attribute, and does not provide the same
|
|
safety guarantee as REQUIRES. In particular:
|
|
|
|
* A function which acquires a capability does not have to exclude it.
|
|
* A function which calls a function that excludes a capability does not
|
|
have transitively exclude that capability.
|
|
|
|
As a result, EXCLUDES can easily produce false negatives:
|
|
|
|
.. code-block:: c++
|
|
|
|
class Foo {
|
|
Mutex mu;
|
|
|
|
void foo() {
|
|
mu.Lock();
|
|
bar(); // No warning.
|
|
baz(); // No warning.
|
|
mu.Unlock();
|
|
}
|
|
|
|
void bar() { // No warning. (Should have EXCLUDES(mu)).
|
|
mu.Lock();
|
|
// ...
|
|
mu.Unlock();
|
|
}
|
|
|
|
void baz() {
|
|
bif(); // No warning. (Should have EXCLUDES(mu)).
|
|
}
|
|
|
|
void bif() EXCLUDES(mu);
|
|
};
|
|
|
|
|
|
Negative requirements are an alternative EXCLUDES that provide
|
|
a stronger safety guarantee. A negative requirement uses the REQUIRES
|
|
attribute, in conjunction with the ``!`` operator, to indicate that a capability
|
|
should *not* be held.
|
|
|
|
For example, using ``REQUIRES(!mu)`` instead of ``EXCLUDES(mu)`` will produce
|
|
the appropriate warnings:
|
|
|
|
.. code-block:: c++
|
|
|
|
class FooNeg {
|
|
Mutex mu;
|
|
|
|
void foo() REQUIRES(!mu) { // foo() now requires !mu.
|
|
mu.Lock();
|
|
bar();
|
|
baz();
|
|
mu.Unlock();
|
|
}
|
|
|
|
void bar() {
|
|
mu.Lock(); // WARNING! Missing REQUIRES(!mu).
|
|
// ...
|
|
mu.Unlock();
|
|
}
|
|
|
|
void baz() {
|
|
bif(); // WARNING! Missing REQUIRES(!mu).
|
|
}
|
|
|
|
void bif() REQUIRES(!mu);
|
|
};
|
|
|
|
|
|
Negative requirements are an experimental feature which is off by default,
|
|
because it will produce many warnings in existing code. It can be enabled
|
|
by passing ``-Wthread-safety-negative``.
|
|
|
|
|
|
.. _faq:
|
|
|
|
Frequently Asked Questions
|
|
==========================
|
|
|
|
(Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
|
|
|
|
(A) Attributes are part of the formal interface of a function, and should
|
|
always go in the header, where they are visible to anything that includes
|
|
the header. Attributes in the .cpp file are not visible outside of the
|
|
immediate translation unit, which leads to false negatives and false positives.
|
|
|
|
|
|
(Q) "*Mutex is not locked on every path through here?*" What does that mean?
|
|
|
|
(A) See :ref:`conditional_locks`, below.
|
|
|
|
|
|
.. _limitations:
|
|
|
|
Known Limitations
|
|
=================
|
|
|
|
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.
|
|
|
|
.. code-block:: c++
|
|
|
|
class Foo;
|
|
|
|
class Bar {
|
|
void bar(Foo* f) REQUIRES(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 workaround is to (ab)use the ``RETURN_CAPABILITY`` attribute to provide a
|
|
public *name* for a private mutex, without actually exposing the underlying
|
|
mutex. For example:
|
|
|
|
.. code-block:: c++
|
|
|
|
class MyClass {
|
|
private:
|
|
Mutex mu;
|
|
|
|
public:
|
|
// For thread safety analysis only. Does not need to be defined.
|
|
Mutex* getMu() RETURN_CAPABILITY(mu);
|
|
|
|
void doSomething() REQUIRES(mu);
|
|
};
|
|
|
|
void doSomethingTwice(MyClass& c) REQUIRES(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.
|
|
|
|
|
|
.. _conditional_locks:
|
|
|
|
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:
|
|
|
|
.. code-block:: c++
|
|
|
|
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 inline any method calls. As a result, code such as the
|
|
following will not work:
|
|
|
|
.. code-block:: c++
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
.. code-block:: c++
|
|
|
|
class MutexUnlocker {
|
|
Mutex* mu;
|
|
|
|
public:
|
|
MutexUnlocker(Mutex* m) RELEASE(m) : mu(m) { mu->Unlock(); }
|
|
~MutexUnlocker() ACQUIRE(mu) { mu->Lock(); }
|
|
};
|
|
|
|
Mutex mutex;
|
|
void test() REQUIRES(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 :ref:`mutexheader`. However, it doesn't work because the analysis
|
|
doesn't know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles
|
|
aliasing for MutexLocker, but does so only for that particular pattern.
|
|
|
|
|
|
ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
|
|
-------------------------------------------------------------------------
|
|
|
|
To be fixed in a future update.
|
|
|
|
|
|
.. _mutexheader:
|
|
|
|
mutex.h
|
|
=======
|
|
|
|
Thread safety analysis can be used with any threading library, but it does
|
|
require that the threading API be wrapped in classes and methods which have the
|
|
appropriate annotations. The following code provides ``mutex.h`` as an example;
|
|
these methods should be filled in to call the appropriate underlying
|
|
implementation.
|
|
|
|
|
|
.. code-block:: c++
|
|
|
|
|
|
#ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
#define THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
|
|
// Enable thread safety attributes only with clang.
|
|
// The attributes can be safely erased when compiling with other compilers.
|
|
#if defined(__clang__) && (!defined(SWIG))
|
|
#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
|
|
#else
|
|
#define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
|
|
#endif
|
|
|
|
#define CAPABILITY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(capability(x))
|
|
|
|
#define SCOPED_CAPABILITY \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
|
|
|
|
#define GUARDED_BY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
|
|
|
|
#define PT_GUARDED_BY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
|
|
|
|
#define ACQUIRED_BEFORE(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
|
|
|
|
#define ACQUIRED_AFTER(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
|
|
|
|
#define REQUIRES(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))
|
|
|
|
#define REQUIRES_SHARED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))
|
|
|
|
#define ACQUIRE(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))
|
|
|
|
#define ACQUIRE_SHARED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
|
|
|
|
#define RELEASE(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
|
|
|
|
#define RELEASE_SHARED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
|
|
|
|
#define RELEASE_GENERIC(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
|
|
|
|
#define TRY_ACQUIRE(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
|
|
|
|
#define TRY_ACQUIRE_SHARED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
|
|
|
|
#define EXCLUDES(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
|
|
|
|
#define ASSERT_CAPABILITY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))
|
|
|
|
#define ASSERT_SHARED_CAPABILITY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))
|
|
|
|
#define RETURN_CAPABILITY(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
|
|
|
|
#define NO_THREAD_SAFETY_ANALYSIS \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
|
|
|
|
|
|
// Defines an annotated interface for mutexes.
|
|
// These methods can be implemented to use any internal mutex implementation.
|
|
class CAPABILITY("mutex") Mutex {
|
|
public:
|
|
// Acquire/lock this mutex exclusively. Only one thread can have exclusive
|
|
// access at any one time. Write operations to guarded data require an
|
|
// exclusive lock.
|
|
void Lock() ACQUIRE();
|
|
|
|
// Acquire/lock this mutex for read operations, which require only a shared
|
|
// lock. This assumes a multiple-reader, single writer semantics. Multiple
|
|
// threads may acquire the mutex simultaneously as readers, but a writer
|
|
// must wait for all of them to release the mutex before it can acquire it
|
|
// exclusively.
|
|
void ReaderLock() ACQUIRE_SHARED();
|
|
|
|
// Release/unlock an exclusive mutex.
|
|
void Unlock() RELEASE();
|
|
|
|
// Release/unlock a shared mutex.
|
|
void ReaderUnlock() RELEASE_SHARED();
|
|
|
|
// Generic unlock, can unlock exclusive and shared mutexes.
|
|
void GenericUnlock() RELEASE_GENERIC();
|
|
|
|
// Try to acquire the mutex. Returns true on success, and false on failure.
|
|
bool TryLock() TRY_ACQUIRE(true);
|
|
|
|
// Try to acquire the mutex for read operations.
|
|
bool ReaderTryLock() TRY_ACQUIRE_SHARED(true);
|
|
|
|
// Assert that this mutex is currently held by the calling thread.
|
|
void AssertHeld() ASSERT_CAPABILITY(this);
|
|
|
|
// Assert that is mutex is currently held for read operations.
|
|
void AssertReaderHeld() ASSERT_SHARED_CAPABILITY(this);
|
|
|
|
// For negative capabilities.
|
|
const Mutex& operator!() const { return *this; }
|
|
};
|
|
|
|
// Tag types for selecting a constructor.
|
|
struct adopt_lock_t {} inline constexpr adopt_lock = {};
|
|
struct defer_lock_t {} inline constexpr defer_lock = {};
|
|
struct shared_lock_t {} inline constexpr shared_lock = {};
|
|
|
|
// MutexLocker is an RAII class that acquires a mutex in its constructor, and
|
|
// releases it in its destructor.
|
|
class SCOPED_CAPABILITY MutexLocker {
|
|
private:
|
|
Mutex* mut;
|
|
bool locked;
|
|
|
|
public:
|
|
// Acquire mu, implicitly acquire *this and associate it with mu.
|
|
MutexLocker(Mutex *mu) ACQUIRE(mu) : mut(mu), locked(true) {
|
|
mu->Lock();
|
|
}
|
|
|
|
// Assume mu is held, implicitly acquire *this and associate it with mu.
|
|
MutexLocker(Mutex *mu, adopt_lock_t) REQUIRES(mu) : mut(mu), locked(true) {}
|
|
|
|
// Acquire mu in shared mode, implicitly acquire *this and associate it with mu.
|
|
MutexLocker(Mutex *mu, shared_lock_t) ACQUIRE_SHARED(mu) : mut(mu), locked(true) {
|
|
mu->ReaderLock();
|
|
}
|
|
|
|
// Assume mu is held in shared mode, implicitly acquire *this and associate it with mu.
|
|
MutexLocker(Mutex *mu, adopt_lock_t, shared_lock_t) REQUIRES_SHARED(mu)
|
|
: mut(mu), locked(true) {}
|
|
|
|
// Assume mu is not held, implicitly acquire *this and associate it with mu.
|
|
MutexLocker(Mutex *mu, defer_lock_t) EXCLUDES(mu) : mut(mu), locked(false) {}
|
|
|
|
// Release *this and all associated mutexes, if they are still held.
|
|
// There is no warning if the scope was already unlocked before.
|
|
~MutexLocker() RELEASE() {
|
|
if (locked)
|
|
mut->GenericUnlock();
|
|
}
|
|
|
|
// Acquire all associated mutexes exclusively.
|
|
void Lock() ACQUIRE() {
|
|
mut->Lock();
|
|
locked = true;
|
|
}
|
|
|
|
// Try to acquire all associated mutexes exclusively.
|
|
bool TryLock() TRY_ACQUIRE(true) {
|
|
return locked = mut->TryLock();
|
|
}
|
|
|
|
// Acquire all associated mutexes in shared mode.
|
|
void ReaderLock() ACQUIRE_SHARED() {
|
|
mut->ReaderLock();
|
|
locked = true;
|
|
}
|
|
|
|
// Try to acquire all associated mutexes in shared mode.
|
|
bool ReaderTryLock() TRY_ACQUIRE_SHARED(true) {
|
|
return locked = mut->ReaderTryLock();
|
|
}
|
|
|
|
// Release all associated mutexes. Warn on double unlock.
|
|
void Unlock() RELEASE() {
|
|
mut->Unlock();
|
|
locked = false;
|
|
}
|
|
|
|
// Release all associated mutexes. Warn on double unlock.
|
|
void ReaderUnlock() RELEASE() {
|
|
mut->ReaderUnlock();
|
|
locked = false;
|
|
}
|
|
};
|
|
|
|
|
|
#ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
|
|
// The original version of thread safety analysis the following attribute
|
|
// definitions. These use a lock-based terminology. They are still in use
|
|
// by existing thread safety code, and will continue to be supported.
|
|
|
|
// Deprecated.
|
|
#define PT_GUARDED_VAR \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_var)
|
|
|
|
// Deprecated.
|
|
#define GUARDED_VAR \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)
|
|
|
|
// Replaced by REQUIRES
|
|
#define EXCLUSIVE_LOCKS_REQUIRED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
|
|
|
|
// Replaced by REQUIRES_SHARED
|
|
#define SHARED_LOCKS_REQUIRED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
|
|
|
|
// Replaced by CAPABILITY
|
|
#define LOCKABLE \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(lockable)
|
|
|
|
// Replaced by SCOPED_CAPABILITY
|
|
#define SCOPED_LOCKABLE \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
|
|
|
|
// Replaced by ACQUIRE
|
|
#define EXCLUSIVE_LOCK_FUNCTION(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
|
|
|
|
// Replaced by ACQUIRE_SHARED
|
|
#define SHARED_LOCK_FUNCTION(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
|
|
|
|
// Replaced by RELEASE and RELEASE_SHARED
|
|
#define UNLOCK_FUNCTION(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
|
|
|
|
// Replaced by TRY_ACQUIRE
|
|
#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
|
|
|
|
// Replaced by TRY_ACQUIRE_SHARED
|
|
#define SHARED_TRYLOCK_FUNCTION(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
|
|
|
|
// Replaced by ASSERT_CAPABILITY
|
|
#define ASSERT_EXCLUSIVE_LOCK(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
|
|
|
|
// Replaced by ASSERT_SHARED_CAPABILITY
|
|
#define ASSERT_SHARED_LOCK(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
|
|
|
|
// Replaced by EXCLUDE_CAPABILITY.
|
|
#define LOCKS_EXCLUDED(...) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
|
|
|
|
// Replaced by RETURN_CAPABILITY
|
|
#define LOCK_RETURNED(x) \
|
|
THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
|
|
|
|
#endif // USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES
|
|
|
|
#endif // THREAD_SAFETY_ANALYSIS_MUTEX_H
|
|
|