jcip-annotations-20060626/ 0000755 0001750 0001750 00000000000 10721646177 015212 5 ustar twerner twerner jcip-annotations-20060626/META-INF/ 0000755 0001750 0001750 00000000000 10721646177 016352 5 ustar twerner twerner jcip-annotations-20060626/META-INF/MANIFEST.MF 0000644 0001750 0001750 00000000152 10721646177 020002 0 ustar twerner twerner Manifest-Version: 1.0 Ant-Version: Apache Ant 1.6.5 Created-By: 1.6.0_01-b06 (Sun Microsystems Inc.) jcip-annotations-20060626/net/ 0000755 0001750 0001750 00000000000 10721646177 016000 5 ustar twerner twerner jcip-annotations-20060626/net/jcip/ 0000755 0001750 0001750 00000000000 10721646177 016725 5 ustar twerner twerner jcip-annotations-20060626/net/jcip/annotations/ 0000755 0001750 0001750 00000000000 10721646177 021262 5 ustar twerner twerner jcip-annotations-20060626/net/jcip/annotations/GuardedBy.java 0000644 0001750 0001750 00000003627 10721646177 024003 0 ustar twerner twerner /* * Copyright (c) 2005 Brian Goetz and Tim Peierls * Released under the Creative Commons Attribution License * (http://creativecommons.org/licenses/by/2.5) * Official home: http://www.jcip.net * * Any republication or derived work distributed in source code form * must include this copyright and license notice. */ package net.jcip.annotations; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * The field or method to which this annotation is applied can only be accessed * when holding a particular lock, which may be a built-in (synchronization) lock, * or may be an explicit java.util.concurrent.Lock. * * The argument determines which lock guards the annotated field or method: *
this
: The intrinsic lock of the object in whose class the field is defined.
* class-name.this
: For inner classes, it may be necessary to disambiguate 'this';
* the class-name.this designation allows you to specify which 'this' reference is intended
* itself
: For reference fields only; the object to which the field refers.
* field-name
: The lock object is referenced by the (instance or static) field
* specified by field-name.
* class-name.field-name
: The lock object is reference by the static field specified
* by class-name.field-name.
* method-name()
: The lock object is returned by calling the named nil-ary method.
* class-name.class
: The Class object for the specified class should be used as the lock object.
* * Immutable objects are inherently thread-safe; they may be passed between threads or * published without synchronization. */ @Documented @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface Immutable { } jcip-annotations-20060626/net/jcip/annotations/NotThreadSafe.java 0000644 0001750 0001750 00000001477 10721646177 024625 0 ustar twerner twerner package net.jcip.annotations; import java.lang.annotation.*; /* * Copyright (c) 2005 Brian Goetz and Tim Peierls * Released under the Creative Commons Attribution License * (http://creativecommons.org/licenses/by/2.5) * Official home: http://www.jcip.net * * Any republication or derived work distributed in source code form * must include this copyright and license notice. */ /** * The class to which this annotation is applied is not thread-safe. * This annotation primarily exists for clarifying the non-thread-safety of a class * that might otherwise be assumed to be thread-safe, despite the fact that it is a bad * idea to assume a class is thread-safe without good reason. * @see ThreadSafe */ @Documented @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface NotThreadSafe { } jcip-annotations-20060626/net/jcip/annotations/ThreadSafe.java 0000644 0001750 0001750 00000001571 10721646177 024137 0 ustar twerner twerner package net.jcip.annotations; import java.lang.annotation.*; /* * Copyright (c) 2005 Brian Goetz and Tim Peierls * Released under the Creative Commons Attribution License * (http://creativecommons.org/licenses/by/2.5) * Official home: http://www.jcip.net * * Any republication or derived work distributed in source code form * must include this copyright and license notice. */ /** * The class to which this annotation is applied is thread-safe. This means that * no sequences of accesses (reads and writes to public fields, calls to public methods) * may put the object into an invalid state, regardless of the interleaving of those actions * by the runtime, and without requiring any additional synchronization or coordination on the * part of the caller. */ @Documented @Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME) public @interface ThreadSafe { } jcip-annotations-20060626/net/jcip/annotations/package.html 0000644 0001750 0001750 00000005070 10721646177 023545 0 ustar twerner twerner
Class, field, and method level annotations for describing thread-safety policies.
Three class-level annotations describe the intended thread-safety promises of a class:
@Immutable
, @ThreadSafe
, and @NotThreadSafe
.
@Immutable
means that the class is immutable,
and implies @ThreadSafe
.
@NotThreadSafe
is optional;
if 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 code-analysis 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.
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.
The @GuardedBy(lock)
annotation documents that a field or method should
be accessed only with a specific lock held.
This software is copyright (c) 2005 Brian Goetz and Tim Peierls and is released under the Creative Commons Attribution License (http://creativecommons.org/licenses/by/2.5). The official home for this software is http://www.jcip.net. Any republication or derived work distributed in source code form must include the copyright and license notice.