14 * version 2 for more details (a copy is included in the LICENSE file that
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.AOTSafeClassInitializer;
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
34 /**
35 * Abstract base class for reference objects. This class defines the
36 * operations common to all reference objects. Because reference objects are
37 * implemented in close cooperation with the garbage collector, this class may
38 * not be subclassed directly.
39 * @param <T> the type of the referent
40 *
41 * @author Mark Reinhold
42 * @since 1.2
43 * @sealedGraph
44 */
45 @AOTSafeClassInitializer
46 public abstract sealed class Reference<@jdk.internal.RequiresIdentity 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.
512
513 /**
514 * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
515 * meaningfully cloned. Construct a new {@code Reference} instead.
516 *
517 * @return never returns normally
518 * @throws CloneNotSupportedException always
519 */
520 @Override
521 protected Object clone() throws CloneNotSupportedException {
522 throw new CloneNotSupportedException();
523 }
524
525 /* -- Constructors -- */
526
527 Reference(T referent) {
528 this(referent, null);
529 }
530
531 Reference(T referent, ReferenceQueue<? super T> queue) {
532 this.referent = referent;
533 this.queue = (queue == null) ? ReferenceQueue.NULL_QUEUE : queue;
534 }
535
536 /**
537 * Ensures that the given object remains
538 * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>.
539 * This reachability is assured regardless of any optimizing transformations
540 * the virtual machine may perform that might otherwise allow the object to
541 * become unreachable (see JLS {@jls 12.6.1}). Thus, the given object is not
542 * reclaimable by garbage collection at least until after the invocation of
543 * this method. References to the given object will not be cleared (or
544 * enqueued, if applicable) by the garbage collector until after invocation
545 * of this method.
546 * Invocation of this method does not itself initiate reference processing,
547 * garbage collection, or finalization.
548 *
549 * <p> This method establishes an ordering for <em>strong reachability</em>
550 * with respect to garbage collection. It controls relations that are
551 * otherwise only implicit in a program -- the reachability conditions
|
14 * version 2 for more details (a copy is included in the LICENSE file that
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.AOTSafeClassInitializer;
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
34 import java.util.Objects;
35
36 /**
37 * Abstract base class for reference objects. This class defines the
38 * operations common to all reference objects. Because reference objects are
39 * implemented in close cooperation with the garbage collector, this class may
40 * not be subclassed directly.
41 *
42 * <div class="preview-block">
43 * <div class="preview-comment">
44 * The referent must have {@linkplain Objects#hasIdentity(Object) object identity}.
45 * When preview features are enabled, attempts to create a reference
46 * to a {@linkplain Class#isValue value object} result in an {@link IdentityException}.
47 * </div>
48 * </div>
49 * @param <T> the type of the referent
50 *
51 * @author Mark Reinhold
52 * @since 1.2
53 * @sealedGraph
54 */
55 @AOTSafeClassInitializer
56 public abstract sealed class Reference<@jdk.internal.RequiresIdentity T>
57 permits PhantomReference, SoftReference, WeakReference, FinalReference {
58
59 /* The state of a Reference object is characterized by two attributes. It
60 * may be either "active", "pending", or "inactive". It may also be
61 * either "registered", "enqueued", "dequeued", or "unregistered".
62 *
63 * Active: Subject to special treatment by the garbage collector. Some
64 * time after the collector detects that the reachability of the
65 * referent has changed to the appropriate state, the collector
66 * "notifies" the reference, changing the state to either "pending" or
67 * "inactive".
68 * referent != null; discovered = null, or in GC discovered list.
522
523 /**
524 * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
525 * meaningfully cloned. Construct a new {@code Reference} instead.
526 *
527 * @return never returns normally
528 * @throws CloneNotSupportedException always
529 */
530 @Override
531 protected Object clone() throws CloneNotSupportedException {
532 throw new CloneNotSupportedException();
533 }
534
535 /* -- Constructors -- */
536
537 Reference(T referent) {
538 this(referent, null);
539 }
540
541 Reference(T referent, ReferenceQueue<? super T> queue) {
542 if (referent != null) {
543 Objects.requireIdentity(referent);
544 }
545 this.referent = referent;
546 this.queue = (queue == null) ? ReferenceQueue.NULL_QUEUE : queue;
547 }
548
549 /**
550 * Ensures that the given object remains
551 * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>.
552 * This reachability is assured regardless of any optimizing transformations
553 * the virtual machine may perform that might otherwise allow the object to
554 * become unreachable (see JLS {@jls 12.6.1}). Thus, the given object is not
555 * reclaimable by garbage collection at least until after the invocation of
556 * this method. References to the given object will not be cleared (or
557 * enqueued, if applicable) by the garbage collector until after invocation
558 * of this method.
559 * Invocation of this method does not itself initiate reference processing,
560 * garbage collection, or finalization.
561 *
562 * <p> This method establishes an ordering for <em>strong reachability</em>
563 * with respect to garbage collection. It controls relations that are
564 * otherwise only implicit in a program -- the reachability conditions
|