Clang的线程安全分析模块Thread Safety Analysis

背景

最近在浏览 Android 11 源代码的时候，发现在ART虚拟机头文件 art_method.h 中，存在大量的类似REQUIRES_SHARED(Locks::mutator_lock_); 的代码。

如下：

在代码中搜索REQUIRES_SHARED，没找到相关定义，刚刚开始百思不解。后来查询了一下，才找到相关的介绍。

REQUIRES_SHARED这个宏是Clang用于静态线程安全代码分析的宏，相关定义在mutex.h。

这个宏的目的是通知Clang在静态代码分析的时候，确保在调用被修饰的函数的时候，是进行加锁操作的。

后面的Locks::mutator_lock_为需要使用哪个锁对象进行加锁操作，这个变量的定义在 locks.cc 中。

介绍

Clang的线程安全分析模块是C++语言的一个扩展，能对代码中潜在的竞争条件进行警告。这种分析是完全静态的（即编译时进行），没有运行时的消耗。当前这个功能还在开发中，但它已经具备了足够的成熟度，可以被部署到生产环境中。它由Google开发，同时受到CERT（United States Computer Emergency Readiness Team，美国互联网应急中心）/SEI（Software Engineering Institute，软件工程中心）的协助，并在Google的内部代码中被广泛应用。

对于多线程的程序来说，线程安全分析很像一个类型系统。在一个多线程的环境中，程序员除了可以声明一个数据的类型（比如，int, float等）之外，还可以声明对数据的访问是如何被控制的。例如，如果变量foo受到互斥锁mu的监控，那么如果如果一段代码在读或者写foo之前没有加锁，就会发出警告。同样，如果一段仅应被GUI线程访问的代码被其它线程访问了，也会发出警告。

入门

这段代码说明了线程安全分析背后的基本概念。GUARDED_BY属性声明，一个线程在读或写balance变量之前，必须先锁住mu，由此保证对balance的增加和降低操作都是原子的。同样，REQUIRES声明了在调用线程调用withdrawImpl方法之前，必须先锁住mu。因为调用者已经在方法调用之前锁住了mu，因此在方法体内部修改balance就是安全的了。

depositeImpl方法没有REQUIRES生命，因此分析模块给出了一个警告。线程安全分析模块并不是进程内部的，因此对调用者的需求必须被显式的声明。在transferFrom方法内部也有一个警告，因为尽管方法锁住了this->mu，它没有锁住b.mu，分析模块知道这是两个不同的锁，分属两个不同的对象。

最后，在withdraw方法内部也有一个警告，因为它没有解锁mu。每一个上锁操作必须有一个配对的解锁操作，分析模块将检测成对的上锁和解锁操作。一个函数可以仅上锁而不解锁（反之亦然），但这必须被显式标注（使用ACQUIRE/RELEASE）。

运行分析

为了运行分析模块，只需要加入编译选项 -Wthread-safety，比如

注意，这段代码假设已经有一个正确的标注文件mutex.h存在，这个文件中声明了哪个方法执行了上锁、解锁的操作。

基本概念：监护权

线程安全分析提供了一种使用“监护权”保护资源的方法。“资源”可以是数据成员，或者可以访问底层资源的过程或方法。分析模块保证了，除非调用者线程拥有了对于资源的监护权（调用一个方法，或者读/写一个数据），否则它是无法访问到资源的。监护权被绑定到一些具名的C++对象上，这些对象声明了专用的方法来获取和释放监护权。这些对象的名称被用来识别监护权。最常见的例子就是互斥锁。例如，如果mu是一个互斥锁，那么调用mu.Lock()使得调用者线程拥有了mu所保护的数据的监护权。同样的，调用mu.Unlock()释放监护权。

线程可以排他的或者共享的拥有监护权。一个排他的监护权每次仅能被一个线程拥有，而一个共享的监护权可以同时被多个线程拥有。这个机制使得多读一写的模式成为可能。写操作需要排他的监护权，而读操作仅需要共享的监护权。

在程序执行的给定时刻，每个线程拥有各自的监护权集合（该线程锁住的互斥锁的集合）。它们类似于钥匙或者令牌，允许线程访问这些资源。跟物理上的安全钥匙一样，线程不能复制、也不能销毁监护权。一个线程只能把监护权释放给另外一个线程，或者从另外一个线程获得监护权。安全起见，分析模块的标识不清楚具体获取和释放监护权的机制，它假设底层实现（例如，互斥锁的实现）能够恰当的完成这个任务。

在程序运行的某个具体时刻，某个线程拥有的监护权集合是一个运行时的概念。静态的任务是对这个集合（也被称为监护权环境）进行估计。分析模块会通过静态分析描述程序任何执行节点的监护权环境。这个估计，是对实际运行时监护权环境的保守估计。

应用指导

线程安全分析模块使用属性来声明线程约束。属性必须被绑定到具名的声明，比如类、方法、数据成员。我们强烈建议用户为这些不同的属性定义宏，示例请参见以下的mutex.h文件。接下来的说明将假设使用了宏。

由于历史原因，线程安全分析模块的早期版本是用了以锁为中心的宏名称。为了适应更普适的模型，这些宏被更改了名称。之前的名称仍然在使用，在接下来的文档里会特别指明。

GUARDED_BY(c) 和 PT_GUARDED_BY(c)

GUARDED_BY是一个应用在数据成员上的属性，它声明了数据成员被给定的监护权保护。对于数据的读操作需要共享的访问权限，而写操作需要独占的访问权限。

PT_GUARDED_BY与之类似，只不过它是为指针和智能指针准备的。对数据成员（指针）本身没有任何限制，它保护的是指针指向的数据。

REQUIRES(...)，REQUIRES_SHARED(...)

早期的版本是EXCLUSIVE_LOCKS_REQUIRED，SHARED_LOCKS_REQUIRED

REQUIRES是作用于方法或者函数上的属性，它表明了调用线程必须独享给定的监护权。可以指定不止一个监护权。监护权必须在函数的入口处、出口处同时被声明。

REQUIRES_SHARED与之类似，只不过仅需要共享的访问权限。

ACQUIRE(...)，ACQUIRE_SHARED(...)，RELEASE(...)，RELEASE_SHARED(...)

早期版本是EXECLUSIVE_LOCK_FUNCTION，SHARED_LOCK_FUNCTION，UNLOCK_FUNCTION

ACQUIRE是一个作用在函数或者方法上的属性，它声明了这个函数或方法需要一个监护权，但不会释放它。调用者在调用之前不能拥有监护权，在调用之后需要获得监护权。ACQUIRE_SHARED与之类似。

RELEASE和RELEASE_SHARED声明，函数必须释放监护权。调用者在调用之前必须拥有监护权，在调用之后将失去监护权。监护权是共享还是排他的，并不重要。

如果没有向ACQUIRE或RELEASE传递参数，那么this将会成为它的默认参数，分析模块将不会检查它修饰的函数体。这种模式通常被在抽象接口下隐藏具体锁细节的类使用（译者注：为了不向外界暴露锁的实现细节，将锁作为类的私有数据，因此，对共有函数声明不带参数的ACQUIRE/RELEASE，相当于对当前对象——也相当于对这个私有的锁——进行加锁/释放锁操作），示例如下：

EXCLUDES(...)

早期版本LOCKS_EXCLUDED

EXCLUDES是一种函数或方法的属性，用来声明调用者绝对不能拥有监护权。这样做的目的是为了防止死锁。很多互斥锁的实现是不允许重入的，因此如果一个函数二次申请一个互斥锁，会引起死锁。

与REQUIRES不同，EXCLUDES是可选的。如果该属性缺失的话，分析模块不会发出警告，这在某些情况下可能会产生某些错误的负样本（本来应该在函数内部进行加锁和释放锁，但没有这么做，分析系统也没有警告，这样在实际运行中可能会出现错误）。这个问题将在“负监护权”章节中讨论。

NO_THREAD_SAFETY_ANALYSIS

NO_THREAD_SAFETY_ANALYSIS是一种函数或方法的属性，它意味着对该函数关闭线程安全分析。它为以下两种函数的实现提供了可能，第一，故意设计的线程不安全的代码，第二，代码是线程安全的，但是对于线程安全分析模块来说太复杂，模块无法理解。第二种情况将在“已知限制”章节中讨论。

与其它属性不同的是，NO_THREAD_SAFETY_ANALYSIS不是函数接口的一部分，它需要被放在源文件（cc或cpp）而不是头文件（h）中。

RETURN_CAPABILITY(c)

早期版本LOCK_RETURNED

RETURN_CAPABILITY是一种函数或方法的属性，它声明了该函数将返回一个给定监护权的引用。通常用来修饰会返回互斥锁的getter方法。

ACQUIRED_BEFORE(...)，ACQUIRED_AFTER(...)

ACQUIRED_BEFORE和ACQUIRED_AFTER是成员变量的属性，特别是用来声明互斥锁或其他监护权。这种声明在互斥锁之间强加了一个获取的优先级，目的是为了防止死锁。

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

GUARDED_VAR和PT_GUARDED_VAR

参考链接

---

• 一个thread safety annotations例子
• Clang 12 Thread Safety Analysis
• clang的线程安全分析模块 thread safety analysis
• clang之Thread Safety Analysis