跟我学（Effective Java 2）第70条:线程安全性的文档化

第70条:线程安全性的文档化

在一个方法声明中出现synchronized修饰符，这是个实现细节，并不是导出的API的一部分。它并不一定表明这个方法是线程安全的。

线程安全性有多种级别。一个类为了可被多个线程安全的使用，必须在文档中清楚地说明他所支持的线程安全性级别。

1 不可变的（immutable）——这个类的实例是不变的。所以，不需要外部的同步。 这样的例子包括String、Long和BigInteger。

2 无条件的线程安全（unconditionally thread-safe）——这个类的实例是可变的，但是这个类有足够的内部同步，所以，它的实例可以被并发使用，无需任何外部同步。 其例子包括Random和ConcurrentHashMap。

3 有条件的线程安全（conditionally thread-safe）——除了有些方法为进行安全的并发使用而需要外部同步之外，这种线程安全级别与无条件的线程安全相同。 这样的例子包括Collections.synchronized包装返回的集合，他们的迭代器要求外部同步。

4 非线程安全（not thread-safe）——这个类的实例是可变的。为了并发的使用他们，客户必须利用自己选择的外部同步包围每个方法调用（或者调用序列）。 这样的例子包括通用的集合实现，例如ArrayList和HashMap。

5 线程对立的（thread-hostile）——这个类不能安全的被多个线程并发使用，即使所有方法调用都被外部同步包围。 线程对立的根源通常在于，没有同步的修改静态数据。没有人会有意编写一个线程对立的类，基本已淘汰。

值得注意的是有条件线程安全，它必须指明哪个方法调用序列需要外部同步，以及在执行这些序列的时候要获得哪把锁。而无条件的线程安全类，应该考虑使用私有锁对象（private lock object）来代替同步的方法。

每个类都应该利用严谨的说明或者线程安全注解，清楚地在文档中说明它的线程安全属性。synchronized修饰符与这个文档毫无关系。有条件的线程安全类和无条件的线程安全类应该按照上述规范编写实现文档。这样可以防止客户端程序和子类的不同步干扰，让你能够在后续的版本中灵活地对并发控制采用更加复杂的方法。