< prev index next >

src/java.base/share/classes/java/lang/ref/Reference.java

Print this page

 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.lang.ref;
 27 
 28 import jdk.internal.misc.Unsafe;
 29 import jdk.internal.vm.annotation.ForceInline;
 30 import jdk.internal.vm.annotation.IntrinsicCandidate;
 31 import jdk.internal.access.JavaLangRefAccess;
 32 import jdk.internal.access.SharedSecrets;
 33 import jdk.internal.ref.Cleaner;
 34 


 35 /**
 36  * Abstract base class for reference objects.  This class defines the
 37  * operations common to all reference objects.  Because reference objects are
 38  * implemented in close cooperation with the garbage collector, this class may
 39  * not be subclassed directly.




 40  * @param <T> the type of the referent
 41  *
 42  * @author   Mark Reinhold
 43  * @since    1.2
 44  */
 45 
 46 public abstract sealed class Reference<T>
 47     permits PhantomReference, SoftReference, WeakReference, FinalReference {
 48 
 49     /* The state of a Reference object is characterized by two attributes.  It
 50      * may be either "active", "pending", or "inactive".  It may also be
 51      * either "registered", "enqueued", "dequeued", or "unregistered".
 52      *
 53      *   Active: Subject to special treatment by the garbage collector.  Some
 54      *   time after the collector detects that the reachability of the
 55      *   referent has changed to the appropriate state, the collector
 56      *   "notifies" the reference, changing the state to either "pending" or
 57      *   "inactive".
 58      *   referent != null; discovered = null, or in GC discovered list.
 59      *

488      * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
489      * meaningfully cloned. Construct a new {@code Reference} instead.
490      *
491      * @return never returns normally
492      * @throws  CloneNotSupportedException always
493      *
494      * @since 11
495      */
496     @Override
497     protected Object clone() throws CloneNotSupportedException {
498         throw new CloneNotSupportedException();
499     }
500 
501     /* -- Constructors -- */
502 
503     Reference(T referent) {
504         this(referent, null);
505     }
506 
507     Reference(T referent, ReferenceQueue<? super T> queue) {



508         this.referent = referent;
509         this.queue = (queue == null) ? ReferenceQueue.NULL : queue;
510     }
511 
512     /**
513      * Ensures that the object referenced by the given reference remains
514      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
515      * regardless of any prior actions of the program that might otherwise cause
516      * the object to become unreachable; thus, the referenced object is not
517      * reclaimable by garbage collection at least until after the invocation of
518      * this method.  Invocation of this method does not itself initiate garbage
519      * collection or finalization.
520      *
521      * <p> This method establishes an ordering for <em>strong reachability</em>
522      * with respect to garbage collection.  It controls relations that are
523      * otherwise only implicit in a program -- the reachability conditions
524      * triggering garbage collection.  This method is designed for use in
525      * uncommon situations of premature finalization where using
526      * {@code synchronized} blocks or methods, or using other synchronization
527      * facilities are not possible or do not provide the desired control.  This

 15  * accompanied this code).
 16  *
 17  * You should have received a copy of the GNU General Public License version
 18  * 2 along with this work; if not, write to the Free Software Foundation,
 19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 20  *
 21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 22  * or visit www.oracle.com if you need additional information or have any
 23  * questions.
 24  */
 25 
 26 package java.lang.ref;
 27 
 28 import jdk.internal.misc.Unsafe;
 29 import jdk.internal.vm.annotation.ForceInline;
 30 import jdk.internal.vm.annotation.IntrinsicCandidate;
 31 import jdk.internal.access.JavaLangRefAccess;
 32 import jdk.internal.access.SharedSecrets;
 33 import jdk.internal.ref.Cleaner;
 34 
 35 import java.util.Objects;
 36 
 37 /**
 38  * Abstract base class for reference objects.  This class defines the
 39  * operations common to all reference objects.  Because reference objects are
 40  * implemented in close cooperation with the garbage collector, this class may
 41  * not be subclassed directly.
 42  * <p>
 43  * References can only refer to identity objects.
 44  * Attempts to create a reference to a {@linkplain Class#isValue() value object}
 45  * results in an {@link IdentityException}.
 46  * @param <T> the type of the referent
 47  *
 48  * @author   Mark Reinhold
 49  * @since    1.2
 50  */
 51 
 52 public abstract sealed class Reference<T>
 53     permits PhantomReference, SoftReference, WeakReference, FinalReference {
 54 
 55     /* The state of a Reference object is characterized by two attributes.  It
 56      * may be either "active", "pending", or "inactive".  It may also be
 57      * either "registered", "enqueued", "dequeued", or "unregistered".
 58      *
 59      *   Active: Subject to special treatment by the garbage collector.  Some
 60      *   time after the collector detects that the reachability of the
 61      *   referent has changed to the appropriate state, the collector
 62      *   "notifies" the reference, changing the state to either "pending" or
 63      *   "inactive".
 64      *   referent != null; discovered = null, or in GC discovered list.
 65      *

494      * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
495      * meaningfully cloned. Construct a new {@code Reference} instead.
496      *
497      * @return never returns normally
498      * @throws  CloneNotSupportedException always
499      *
500      * @since 11
501      */
502     @Override
503     protected Object clone() throws CloneNotSupportedException {
504         throw new CloneNotSupportedException();
505     }
506 
507     /* -- Constructors -- */
508 
509     Reference(T referent) {
510         this(referent, null);
511     }
512 
513     Reference(T referent, ReferenceQueue<? super T> queue) {
514         if (referent != null) {
515             Objects.requireIdentity(referent);
516         }
517         this.referent = referent;
518         this.queue = (queue == null) ? ReferenceQueue.NULL : queue;
519     }
520 
521     /**
522      * Ensures that the object referenced by the given reference remains
523      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
524      * regardless of any prior actions of the program that might otherwise cause
525      * the object to become unreachable; thus, the referenced object is not
526      * reclaimable by garbage collection at least until after the invocation of
527      * this method.  Invocation of this method does not itself initiate garbage
528      * collection or finalization.
529      *
530      * <p> This method establishes an ordering for <em>strong reachability</em>
531      * with respect to garbage collection.  It controls relations that are
532      * otherwise only implicit in a program -- the reachability conditions
533      * triggering garbage collection.  This method is designed for use in
534      * uncommon situations of premature finalization where using
535      * {@code synchronized} blocks or methods, or using other synchronization
536      * facilities are not possible or do not provide the desired control.  This
< prev index next >