< 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.vm.annotation.AOTRuntimeSetup;
 29 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
 30 import jdk.internal.vm.annotation.ForceInline;
 31 import jdk.internal.vm.annotation.IntrinsicCandidate;
 32 import jdk.internal.access.JavaLangRefAccess;
 33 import jdk.internal.access.SharedSecrets;
 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  * @sealedGraph
 45  */
 46 @AOTSafeClassInitializer
 47 public abstract sealed class Reference<@jdk.internal.RequiresIdentity T>
 48     permits PhantomReference, SoftReference, WeakReference, FinalReference {
 49 
 50     /* The state of a Reference object is characterized by two attributes.  It
 51      * may be either "active", "pending", or "inactive".  It may also be
 52      * either "registered", "enqueued", "dequeued", or "unregistered".
 53      *
 54      *   Active: Subject to special treatment by the garbage collector.  Some
 55      *   time after the collector detects that the reachability of the
 56      *   referent has changed to the appropriate state, the collector
 57      *   "notifies" the reference, changing the state to either "pending" or
 58      *   "inactive".
 59      *   referent != null; discovered = null, or in GC discovered list.

518 
519     /**
520      * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
521      * meaningfully cloned. Construct a new {@code Reference} instead.
522      *
523      * @return never returns normally
524      * @throws  CloneNotSupportedException always
525      */
526     @Override
527     protected Object clone() throws CloneNotSupportedException {
528         throw new CloneNotSupportedException();
529     }
530 
531     /* -- Constructors -- */
532 
533     Reference(T referent) {
534         this(referent, null);
535     }
536 
537     Reference(T referent, ReferenceQueue<? super T> queue) {



538         this.referent = referent;
539         this.queue = (queue == null) ? ReferenceQueue.NULL_QUEUE : queue;
540     }
541 
542     /**
543      * Ensures that the given object remains
544      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>.
545      * This reachability is assured regardless of any optimizing transformations
546      * the virtual machine may perform that might otherwise allow the object to
547      * become unreachable (see JLS {@jls 12.6.1}). Thus, the given object is not
548      * reclaimable by garbage collection at least until after the invocation of
549      * this method. References to the given object will not be cleared (or
550      * enqueued, if applicable) by the garbage collector until after invocation
551      * of this method.
552      * Invocation of this method does not itself initiate reference processing,
553      * garbage collection, or finalization.
554      *
555      * <p> This method establishes an ordering for <em>strong reachability</em>
556      * with respect to garbage collection.  It controls relations that are
557      * otherwise only implicit in a program -- the reachability conditions

 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.vm.annotation.AOTRuntimeSetup;
 29 import jdk.internal.vm.annotation.AOTSafeClassInitializer;
 30 import jdk.internal.vm.annotation.ForceInline;
 31 import jdk.internal.vm.annotation.IntrinsicCandidate;
 32 import jdk.internal.access.JavaLangRefAccess;
 33 import jdk.internal.access.SharedSecrets;
 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  *
 43  * <div class="preview-block">
 44  *      <div class="preview-comment">
 45  *          The referent must have {@linkplain Objects#hasIdentity(Object) object identity}.
 46  *          When preview features are enabled, attempts to create a reference
 47  *          to a {@linkplain Class#isValue value object} result in an {@link IdentityException}.
 48  *      </div>
 49  * </div>
 50  * @param <T> the type of the referent
 51  *
 52  * @author   Mark Reinhold
 53  * @since    1.2
 54  * @sealedGraph
 55  */
 56 @AOTSafeClassInitializer
 57 public abstract sealed class Reference<@jdk.internal.RequiresIdentity T>
 58     permits PhantomReference, SoftReference, WeakReference, FinalReference {
 59 
 60     /* The state of a Reference object is characterized by two attributes.  It
 61      * may be either "active", "pending", or "inactive".  It may also be
 62      * either "registered", "enqueued", "dequeued", or "unregistered".
 63      *
 64      *   Active: Subject to special treatment by the garbage collector.  Some
 65      *   time after the collector detects that the reachability of the
 66      *   referent has changed to the appropriate state, the collector
 67      *   "notifies" the reference, changing the state to either "pending" or
 68      *   "inactive".
 69      *   referent != null; discovered = null, or in GC discovered list.

528 
529     /**
530      * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
531      * meaningfully cloned. Construct a new {@code Reference} instead.
532      *
533      * @return never returns normally
534      * @throws  CloneNotSupportedException always
535      */
536     @Override
537     protected Object clone() throws CloneNotSupportedException {
538         throw new CloneNotSupportedException();
539     }
540 
541     /* -- Constructors -- */
542 
543     Reference(T referent) {
544         this(referent, null);
545     }
546 
547     Reference(T referent, ReferenceQueue<? super T> queue) {
548         if (referent != null) {
549             Objects.requireIdentity(referent);
550         }
551         this.referent = referent;
552         this.queue = (queue == null) ? ReferenceQueue.NULL_QUEUE : queue;
553     }
554 
555     /**
556      * Ensures that the given object remains
557      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>.
558      * This reachability is assured regardless of any optimizing transformations
559      * the virtual machine may perform that might otherwise allow the object to
560      * become unreachable (see JLS {@jls 12.6.1}). Thus, the given object is not
561      * reclaimable by garbage collection at least until after the invocation of
562      * this method. References to the given object will not be cleared (or
563      * enqueued, if applicable) by the garbage collector until after invocation
564      * of this method.
565      * Invocation of this method does not itself initiate reference processing,
566      * garbage collection, or finalization.
567      *
568      * <p> This method establishes an ordering for <em>strong reachability</em>
569      * with respect to garbage collection.  It controls relations that are
570      * otherwise only implicit in a program -- the reachability conditions
< prev index next >