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
|