The following is a proposal for a project we would like to contribute to Clang. Feel free to discuss.
Google & University of California at Santa Cruz
Thread Safety Attributes for Clang
We would like to add a set of thread safety attributes to Clang. These attributes, based on a prior GCC implementation, will allow for checkable documentation of basic locking policies in multithreaded programs.
The synchronization policies in modern multithreaded code may be poorly documented, and incorrectly inferred by new developers. Furthermore, when these policies are improperly followed they often lead to bugs which are difficult to reproduce and diagnose. One strategy for avoiding concurrency bugs is formal documentation of these synchronization policies. By writing this documentation using attribute-based annotations, Clang can mechanically check and warn about issues that could potentially result in race conditions and deadlocks.
A code sample which demonstrates two of the proposed annotations is below. In this code sample, variables are protected by locks from the Mutex class. This class has been annotated to specify the API used to lock and unlock.
- GUARDED_BY specifies a particular lock should be held when accessing the annotated variable. Violations of this locking policy may lead to data races.
- ACQUIRED_AFTER annotations document the acquisition order between locks that can be held simultaneously by a thread, by specify the locks that need to be acquired before the annotated lock. Violations of this locking policy may lead to deadlocks.
1 #include “thread_annotations.h”
2 #define GUARDED_BY(x) attribute((GUARDED_BY(x)))
3 #define ACQUIRED_AFTER(x) attribute((ACQUIRED_AFTER(x)))
5 Mutex mu1;
6 Mutex mu2 ACQUIRED_AFTER(mu1);
8 int x GUARDED_BY(mu1);
9 int a GUARDED_BY(mu2);
11 void foo()
15 if (x > 2)
16 a = x + 1;
18 a = x - 1;
Sample compiler output:
ex.cc: In function ‘void foo()’:
ex.cc:12: warning: Lock ‘mu1’ is acquired after lock ‘mu2’ (acquired at line 14) but is annotated otherwise
As mentioned, thread safety annotations have been implemented in GCC. A full list of the annotations and descriptions for them can be found here:
These annotations have been in active use in Google’s C++ codebase for a couple of years, so there is a large informal case study of their usefulness. The ideas behind many of these annotations come originally from a research paper .
We are planning to re-implement the GCC thread safety attributes in Clang. We will submit a series of patches to the cfe-commits mailing list. Our current plan for this serie is as follows:
- Basic parsing and semantic checking of the attributes which do not take arguments. In other words, checking whether the attribute is applied in the appropriate context (e.g. to a field, with no arguments).
- Basic parsing and semantic checking of the attributes which do take arguments, but without parsing or checking the arguments themselves. At this point, we will simply discard the tokens making up the arguments.
- Attribute argument parsing.
- Adding the thread safety analysis checks. We will teach the static analysis-based warnings layer to warn for violations of the annotations discussed on the links above.
Once we have this core set of thread safety annotations implemented, we have several directions for future work we would like to pursue. These include supporting additional types of annotations. For example, we would like to extend the system to support annotations for functions which only touch thread-local data and atomic functions which always execute as if they are not interleaved with operations of other threads. We would also like to build an annotation inference system; this system would enable application of the thread safety analysis to large amounts of legacy code.
 C. Flanagan and S. N. Freund. Type-based race detection for Java. In Programming Language Design and Implementation (PLDI), June 2000.