Composing Objects - Java Concurrency in Practice - page 86

ImprovedList adds an additional level of locking using its own intrinsic lock. It does
not care whether the underlying List is thread-safe, because it provides its own consistent
locking that provides thread safety even if the List is not thread-safe or changes its locking
implementation. While the extra layer of synchronization may add some small performance
penalty, [7] the implementation in ImprovedList is less fragile than attempting to mimic
the locking strategy of another object. In effect, we've used the Java monitor pattern to encap-
sulate an existing List , and this is guaranteed to provide thread safety so long as our class
holds the only outstanding reference to the underlying List .
4.5. Documenting Synchronization Policies
Documentation is one of the most powerful (and, sadly, most underutilized) tools for man-
aging thread safety. Users look to the documentation to find out if a class is thread-safe, and
maintainers look to the documentation to understand the implementation strategy so they can
maintain it without inadvertently compromising safety. Unfortunately, both of these constitu-
encies usually find less information in the documentation than they'd like.
Document a class's thread safety guarantees for its clients; document its synchonization
policy for its maintainers.