介绍
Clang的线程安全分析模块是C++语言的一个扩展，能对代码中潜在的竞争条件进行警告。这种分析是完全静态的（即编译时进行），没有运行时的消耗。当前这个功能还在开发中，但它已经具备了足够的成熟度，可以被部署到生产环境中。它由Google开发，同时受到CERT（United States Computer Emergency Readiness Team，美国互联网应急中心）/SEI（Software Engineering Institute，软件工程中心）的协助，并在Google的内部代码中被广泛应用。
对于多线程的程序来说，线程安全分析很像一个类型系统。在一个多线程的环境中，程序员除了可以声明一个数据的类型（比如，int, float等）之外，还可以声明对数据的访问是如何被控制的。例如，如果变量foo受到互斥锁mu的监控，那么如果如果一段代码在读或者写foo之前没有加锁，就会发出警告。同样，如果一段仅应被GUI线程访问的代码被其它线程访问了，也会发出警告。
入门
#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();
}
};这段代码说明了线程安全分析背后的基本概念。GUARDED_BY属性声明，一个线程在读或写balance变量之前，必须先锁住mu，由此保证对balance的增加和降低操作都是原子的。同样，REQUIRES声明了在调用线程调用withdrawImpl方法之前，必须先锁住mu。因为调用者已经在方法调用之前锁住了mu，因此在方法体内部修改balance就是安全的了。
depositeImpl方法没有REQUIRES生命，因此分析模块给出了一个警告。线程安全分析模块并不是进程内部的，因此对调用者的需求必须被显式的声明。在transferFrom方法内部也有一个警告，因为尽管方法锁住了this->mu，它没有锁住b.mu，分析模块知道这是两个不同的锁，分属两个不同的对象。
最后，在withdraw方法内部也有一个警告，因为它没有解锁mu。每一个上锁操作必须有一个配对的解锁操作，分析模块将检测成对的上锁和解锁操作。一个函数可以仅上锁而不解锁（反之亦然），但这必须被显式标注（使用ACQUIRE/RELEASE）。
运行分析
为了运行分析模块，只需要加入编译选项 -Wthread-safety，比如
clang -c -Wthread-safety example.cpp
注意，这段代码假设已经有一个正确的标注文件mutex.h存在，这个文件中声明了哪个方法执行了上锁、解锁的操作。
基本概念：监护权
线程安全分析提供了一种使用“监护权”保护资源的方法。“资源”可以是数据成员，或者可以访问底层资源的过程或方法。分析模块保证了，除非调用者线程拥有了对于资源的监护权（调用一个方法，或者读/写一个数据），否则它是无法访问到资源的。监护权被绑定到一些具名的C++对象上，这些对象声明了专用的方法来获取和释放监护权。这些对象的名称被用来识别监护权。最常见的例子就是互斥锁。例如，如果mu是一个互斥锁，那么调用mu.Lock()使得调用者线程拥有了mu所保护的数据的监护权。同样的，调用mu.Unlock()释放监护权。
线程可以排他的或者共享的拥有监护权。一个排他的监护权每次仅能被一个线程拥有，而一个共享的监护权可以同时被多个线程拥有。这个机制使得多读一写的模式成为可能。写操作需要排他的监护权，而读操作仅需要共享的监护权。
在程序执行的给定时刻，每个线程拥有各自的监护权集合（该线程锁住的互斥锁的集合）。它们类似于钥匙或者令牌，允许线程访问这些资源。跟物理上的安全钥匙一样，线程不能复制、也不能销毁监护权。一个线程只能把监护权释放给另外一个线程，或者从另外一个线程获得监护权。安全起见，分析模块的标识不清楚具体获取和释放监护权的机制，它假设底层实现（例如，互斥锁的实现）能够恰当的完成这个任务。
在程序运行的某个具体时刻，某个线程拥有的监护权集合是一个运行时的概念。静态的任务是对这个集合（也被称为监护权环境）进行估计。分析模块会通过静态分析描述程序任何执行节点的监护权环境。这个估计，是对实际运行时监护权环境的保守估计。
应用指导
线程安全分析模块使用属性来声明线程约束。属性必须被绑定到具名的声明，比如类、方法、数据成员。我们强烈建议用户为这些不同的属性定义宏，示例请参见以下的mutex.h文件。接下来的说明将假设使用了宏。
由于历史原因，线程安全分析模块的早期版本是用了以锁为中心的宏名称。为了适应更普适的模型，这些宏被更改了名称。之前的名称仍然在使用，在接下来的文档里会特别指明。
GUARDED_BY(c) 和 PT_GUARDED_BY(c)
GUARDED_BY是一个应用在数据成员上的属性，它声明了数据成员被给定的监护权保护。对于数据的读操作需要共享的访问权限，而写操作需要独占的访问权限。
PT_GUARDED_BY与之类似，只不过它是为指针和智能指针准备的。对数据成员（指针）本身没有任何限制，它保护的是指针指向的数据。
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(...)
早期的版本是EXCLUSIVE_LOCKS_REQUIRED，SHARED_LOCKS_REQUIRED
REQUIRES是作用于方法或者函数上的属性，它表明了调用线程必须独享给定的监护权。可以指定不止一个监护权。监护权必须在函数的入口处、出口处同时被声明。
REQUIRES_SHARED与之类似，只不过仅需要共享的访问权限。
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(...)
早期版本是EXECLUSIVE_LOCK_FUNCTION，SHARED_LOCK_FUNCTION，UNLOCK_FUNCTION
ACQUIRE是一个作用在函数或者方法上的属性，它声明了这个函数或方法需要一个监护权，但不会释放它。调用者在调用之前不能拥有监护权，在调用之后需要获得监护权。ACQUIRE_SHARED与之类似。
RELEASE和RELEASE_SHARED声明，函数必须释放监护权。调用者在调用之前必须拥有监护权，在调用之后将失去监护权。监护权是共享还是排他的，并不重要。
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.}如果没有向ACQUIRE或RELEASE传递参数，那么this将会成为它的默认参数，分析模块将不会检查它修饰的函数体。这种模式通常被在抽象接口下隐藏具体锁细节的类使用（译者注：为了不向外界暴露锁的实现细节，将锁作为类的私有数据，因此，对共有函数声明不带参数的ACQUIRE/RELEASE，相当于对当前对象——也相当于对这个私有的锁——进行加锁/释放锁操作），示例如下：
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(...)
早期版本LOCKS_EXCLUDED
EXCLUDES是一种函数或方法的属性，用来声明调用者绝对不能拥有监护权。这样做的目的是为了防止死锁。很多互斥锁的实现是不允许重入的，因此如果一个函数二次申请一个互斥锁，会引起死锁。
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();
}与REQUIRES不同，EXCLUDES是可选的。如果该属性缺失的话，分析模块不会发出警告，这在某些情况下可能会产生某些错误的负样本（本来应该在函数内部进行加锁和释放锁，但没有这么做，分析系统也没有警告，这样在实际运行中可能会出现错误）。这个问题将在“负监护权”章节中讨论。
NO_THREAD_SAFETY_ANALYSIS
NO_THREAD_SAFETY_ANALYSIS是一种函数或方法的属性，它意味着对该函数关闭线程安全分析。它为以下两种函数的实现提供了可能，第一，故意设计的线程不安全的代码，第二，代码是线程安全的，但是对于线程安全分析模块来说太复杂，模块无法理解。第二种情况将在“已知限制”章节中讨论。
class Counter {
Mutex mu; int a GUARDED_BY(mu); void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
};与其它属性不同的是，NO_THREAD_SAFETY_ANALYSIS不是函数接口的一部分，它需要被放在源文件（cc或cpp）而不是头文件（h）中。
RETURN_CAPABILITY(c)
早期版本LOCK_RETURNED
RETURN_CAPABILITY是一种函数或方法的属性，它声明了该函数将返回一个给定监护权的引用。通常用来修饰会返回互斥锁的getter方法。
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和ACQUIRED_AFTER是成员变量的属性，特别是用来声明互斥锁或其他监护权。这种声明在互斥锁之间强加了一个获取的优先级，目的是为了防止死锁。
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>)
早期版本LOCKABLE
CAPABILITY是一种类的属性，它意味着该类的对象可以被当做监护权使用。string参数使用错误信息指定了监护权的类型，例如“mutex"。参见之前给出的”Container"示例，或者mutex.h文件中的Mutex类。
SCOPED_CAPABILITY
早期版本SCOPED_LOCKABLE
SCOPED_CAPABILITY是一种类的属性，这种类实现了RAII风格的锁，监护权在构造函数中获取，在析构函数中释放。这种类需要被特别指出，因为构造和析构函数指定的监护权的名称是不一样的，参见mutex.h文件中的MutexLocker类。
TRY_ACQUIRE(<bool>,...)，TRY_ACQUIRE_SHARED(<bool>,...)
早期版本EXECLUSIVE_TRYLOCK_FUNCTION，SHARED_TRYLOCK_FUNCTION
这是一种函数或方法的属性，这些函数或方法试图获取指定的监护权，并且返回一个布尔值表明是否成功。函数的第一个参数必须是true或者false，来说明哪个值表示监护权获取成功，剩余参数等同于ACQUIRE。具体示例参见mutex.h。
ASSERT_CAPABILITY(...)和ASSERT_SHARED_CAPABILITY(...)
早期版本ASSERT_EXECLUSIVE_LOCK，ASSERT_SHARED_LOCK
这是一种函数或方法的属性，它表明该函数将在运行时进行一个安全检查，判断调用线程是否拥有监护权。如果调用线程没有监护权，该函数将会返回空表明调用失败。具体示例详见mutex.h
GUARDED_VAR和PT_GUARDED_VAR
该属性的使用已被抛弃。
（还有部分细节，时间原因就不讲了，详见参考链接）
线程安全分析模块可以被任何线程库使用，不过它要求线程的API被包装在有合适注释的类或者方法里。以下的mutex.h提供了一个示例，这些函数需要被实现，以便调用合适的底层实现。
#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 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(); // 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; }
};// 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;public:
MutexLocker(Mutex *mu) ACQUIRE(mu) : mut(mu) {
mu->Lock();
} ~MutexLocker() RELEASE() {
mut->Unlock();
}
};
#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
原文地址：https://clang.llvm.org/docs/ThreadSafetyAnalysis.html