clang的线程安全分析模块 thread safety analysis

介绍

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