1 <html> 2 <body> 3 <p> 4 Class, field, and method level annotations for describing thread-safety policies. 5 </p> 6 7 <p> 8 Three class-level annotations describe the <em>intended</em> thread-safety promises of a class: 9 <code>@Immutable</code>, <code>@ThreadSafe</code>, and <code>@NotThreadSafe</code>. 10 <code>@Immutable</code> means that the class is immutable, 11 and implies <code>@ThreadSafe</code>. 12 <code>@NotThreadSafe</code> is optional; 13 if a class is not annotated as thread-safe, it should be presumed not to be 14 thread-safe, but if you want to make it extra clear, use 15 <code>@NotThreadSafe</code>. 16 </p> 17 18 <p> 19 These annotations are relatively unintrusive and are beneficial to 20 both users and maintainers. Users can see immediately whether a class 21 is thread-safe, and maintainers can see immediately whether 22 thread-safety guarantees must be preserved. Annotations are also 23 useful to a third constituency: tools. Static code-analysis tools may 24 be able to verify that the code complies with the contract indicated 25 by the annotation, such as verifying that a class annotated with 26 <code>@Immutable</code> actually is immutable. 27 </p> 28 29 <h2>Field and method annotations</h2> 30 31 <p> 32 The class-level annotations above are part of the public documentation 33 for the class. Other aspects of a class's thread-safety strategy are 34 entirely for maintainers and are not part of its public documentation. 35 </p> 36 37 <p> 38 Classes that use locking should document which state variables are 39 guarded with which locks, and which locks are used to guard those 40 variables. A common source of inadvertent non-thread-safety is when a 41 thread-safe class consistently uses locking to guard its state, but is 42 later modified to add either new state variables that are not 43 adequately guarded by locking, or new methods that do not use locking 44 properly to guard the existing state variables. Documenting which 45 variables are guarded by which locks can help prevent both types of 46 omissions. 47 </p> 48 49 <p> 50 The <code>@GuardedBy(lock)</code> annotation documents that a field or method should 51 be accessed only with a specific lock held. 52 </p> 53 54 55 <h2>Copyright and license</h2> 56 <p> 57 This software is copyright (c) 2005 Brian Goetz and Tim Peierls 58 and is released under the Creative Commons Attribution License 59 (http://creativecommons.org/licenses/by/2.5). The official home 60 for this software is http://www.jcip.net. 61 Any republication or derived work distributed in source code form 62 must include the copyright and license notice. 63 </p> 64 65 </body> 66 </html>
