Index
[].] abstractions [See .] AbstractQueuedSynchronizer [See AQS framework.].] acquisition of locks [See locks, acquisition.].].].].].].].].].].].].].]
Index
[].].].] bias [See , pitfalls.].].].].].].]
Index
[].].].].].].].].].] compare-and-swap (CAS) instructions [See .].].].]examples of [See .].]errors [See .].].].].].].].].].].].].].].].].].].].].]
Index
[].].].]handling [See .].] deadly embrace [See .].].].].].].].]examples [See .] destruction [See .].].].]
Index
[].].].]concurrency [See .].].].].]
Index
[].].].].].].].].] flag(s) [See .].].].] [See also RMI framework.] [See also Servlets framework.]
Index
[].].].].].]
Index
[].].].] hijacked signal [See .].].].]
Index
[].].].].].].].].].].].].].].]
Index
[].] JMM (Java Memory Model) [See .].]
Index
[]
Index
[].].].] lightweight processes [See .].].].].]causes [See .]safety vs [See .].].]monitor [See .].].]
Index
[].].].].].].]locks [See .].].].].]
Index
[].] notifyAll
Index
[].].] optimistic concurrency management [See .][See also atomic variabless.] [See also nonblocking synchronization.].].]impact of [See .]reduction [See .]sources [See .]
Index
[], shared data.].].].].].].].].] pessimistic concurrency management [See .].].].].].].].] presentation [See .]lightweight [See .].].].].].]
Index
[].].]
Index
[].].] reaping [See .] recovery, deadlock [See .].].].].].].].].].].]
Index
[].].].].].].]stateless.].].].].] single notification [See .].].].].].].].].].].].].].].]types [See .].]
Index
[]
Index
[].].].].] [See also statistics.].].].].].].].].].].].].].]
Index
[].].].].].].].]
Index
[] value(s) [See .].].].]
Index
[].].] within-thread usage [See .]
Appendix A. Annotations for Concurrency
We've used annotations such as @GuardedBy and @ThreadSafe to show how thread-safety promises and synchronization policies can be documented. This appendix documents these annotations; their source code can be downloaded from this book's website. (There are, of course, additional thread-safety promises and implementation details that should be documented but that are not captured by this minimal set of annotations.)
A.1. Class Annotations
We use three class-level annotations to describe a class's intended thread-safety promises: @Immutable , @ThreadSafe , and @NotThreadSafe . @Immutable means, of course, that the class is immutable, and implies @ThreadSafe . @NotThreadSafe is optionalif a class is not annotated as thread-safe, it should be presumed not to be thread-safe, but if you want to make it extra clear, use @NotThreadSafe .
These annotations are relatively unintrusive and are beneficial to both users and maintainers. Users can see immediately whether a class is thread-safe, and maintainers can see immediately whether thread-safety guarantees must be preserved. Annotations are also useful to a third constituency: tools. Static codeanalysis tools may be able to verify that the code complies with the contract indicated by the annotation, such as verifying that a class annotated with @Immutable actually is immutable.
A.2. Field and Method Annotations
The class-level annotations above are part of the public documentation for the class. Other aspects of a class's thread-safety strategy are entirely for maintainers and are not part of its public documentation.
Classes that use locking should document which state variables are guarded with which locks, and which locks are used to guard those variables. A common source of inadvertent non-thread-safety is when a thread-safe class consistently uses locking to guard its state, but is later modified to add either new state variables that are not adequately guarded by locking, or new methods that do not use locking properly to guard the existing state variables. Documenting which variables are guarded by which locks can help prevent both types of omissions.
@GuardedBy(lock) documents that a field or method should be accessed only with a specific lock held. The lock argument identifies the lock that should be held when accessing the annotated field or method. The possible values for lock are:
@GuardedBy("this") , meaning the intrinsic lock on the containing object (the object of which the method or field is a member);
@GuardedBy(" fieldName ") , meaning the lock associated with the object referenced by the named field, either an intrinsic lock (for fields that do not refer to a Lock ) or an explicit Lock (for fields that refer to a Lock );
@GuardedBy(" ClassName.fieldName ") , like @GuardedBy("fieldName") , but referencing a lock object held in a static field of another class;
@GuardedBy(" methodName ()") , meaning the lock object that is returned by calling the named method;
@GuardedBy(" ClassName .class") , meaning the class literal object for the named class.
Using @GuardedBy to identify each state variable that needs locking and which lock guards it can assist in maintenance and code reviews, and can help automated analysis tools spot potential thread-safety errors.
Bibliography
Ken Arnold, James Gosling, and David Holmes. The Java Programming Language , Fourth Edition. AddisonWesley, 2005.
David F. Bacon, Ravi B. Konuru, Chet Murthy, and Mauricio J. Serrano. Thin Locks: Featherweight Synchronization for Java . In SIGPLAN Conference on Programming Language Design and Implementation , pages 258268, 1998. URL http://citeseer.ist.psu.edu/bacon98thin.html.
Joshua Bloch. Effective Java Programming Language Guide . AddisonWesley, 2001.
Joshua Bloch and Neal Gafter. Java Puzzlers . AddisonWesley, 2005.
Hans Boehm. Destructors, Finalizers, and Synchronization. In POPL '03: Proceedings of the 30th ACM SIGPLAN-SIGACT Symposium on Principles of Programming Languages , pages 262272. ACM Press, 2003. URL http://doi.acm.org/10.1145/604131.604153.
Hans Boehm. Finalization, Threads, and the Java Memory Model. JavaOne presentation , 2005. URL http://developers.sun.com/learning/javaoneonline/2005/coreplatform/TS-3281.pdf.
Joseph Bowbeer. The Last Word in Swing Threads , 2005. URL http://java.sun.com/products/jfc/tsc/articles/threads/threads3.html.
Cliff Click. Performance Myths Exposed. JavaOne presentation , 2003.
Cliff Click. Performance Myths Revisited. JavaOne presentation , 2005. URL http://developers.sun.com/learning/javaoneonline/2005/coreplatform/TS-3268.pdf.
Martin Fowler. Presentation Model , 2005. URL http://www.martinfowler.com/eaaDev/PresentationModel.html.
Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides. Design Patterns . AddisonWesley, 1995.
Martin Gardner. The fantastic combinations of John Conway's new solitaire game 'Life' . Scientific American , October 1970.
James Gosling, Bill Joy, Guy Steele, and Gilad Bracha. The Java Language Specification , Third Edition. AddisonWesley, 2005.
Tim Harris and Keir Fraser. Language Support for Lightweight Transactions . In OOPSLA '03: Proceedings of the 18th Annual ACM SIGPLAN Conference on Object-Oriented Programming, Systems, Languages, and Applications , pages 388402. ACM Press, 2003. URL http://doi.acm.org/10.1145/949305.949340.
Tim Harris, Simon Marlow, Simon Peyton-Jones, and Maurice Herlihy. Composable Memory Transactions . In PPoPP '05: Proceedings of the Tenth ACM SIGPLAN Symposium on Principles and Practice of Parallel Programming , pages 4860. ACM Press, 2005. URL http://doi.acm.org/10.1145/1065944.1065952.