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 * @sealedGraph
45 */
46
47 public abstract sealed class Reference<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.
489 * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
490 * meaningfully cloned. Construct a new {@code Reference} instead.
491 *
492 * @return never returns normally
493 * @throws CloneNotSupportedException always
494 *
495 * @since 11
496 */
497 @Override
498 protected Object clone() throws CloneNotSupportedException {
499 throw new CloneNotSupportedException();
500 }
501
502 /* -- Constructors -- */
503
504 Reference(T referent) {
505 this(referent, null);
506 }
507
508 Reference(T referent, ReferenceQueue<? super T> queue) {
509 this.referent = referent;
510 this.queue = (queue == null) ? ReferenceQueue.NULL : queue;
511 }
512
513 /**
514 * Ensures that the object referenced by the given reference remains
515 * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
516 * regardless of any prior actions of the program that might otherwise cause
517 * the object to become unreachable; thus, the referenced object is not
518 * reclaimable by garbage collection at least until after the invocation of
519 * this method. Invocation of this method does not itself initiate garbage
520 * collection or finalization.
521 *
522 * <p> This method establishes an ordering for <em>strong reachability</em>
523 * with respect to garbage collection. It controls relations that are
524 * otherwise only implicit in a program -- the reachability conditions
525 * triggering garbage collection. This method is designed for use in
526 * uncommon situations of premature finalization where using
527 * {@code synchronized} blocks or methods, or using other synchronization
528 * 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 * The referent must be an {@linkplain Objects#isIdentityObject(Object) identity object}.
44 * Attempts to create a reference to a {@linkplain Objects#isValueObject 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 * @sealedGraph
51 */
52
53 public abstract sealed class Reference<T>
54 permits PhantomReference, SoftReference, WeakReference, FinalReference {
55
56 /* The state of a Reference object is characterized by two attributes. It
57 * may be either "active", "pending", or "inactive". It may also be
58 * either "registered", "enqueued", "dequeued", or "unregistered".
59 *
60 * Active: Subject to special treatment by the garbage collector. Some
61 * time after the collector detects that the reachability of the
62 * referent has changed to the appropriate state, the collector
63 * "notifies" the reference, changing the state to either "pending" or
64 * "inactive".
65 * referent != null; discovered = null, or in GC discovered list.
495 * Throws {@link CloneNotSupportedException}. A {@code Reference} cannot be
496 * meaningfully cloned. Construct a new {@code Reference} instead.
497 *
498 * @return never returns normally
499 * @throws CloneNotSupportedException always
500 *
501 * @since 11
502 */
503 @Override
504 protected Object clone() throws CloneNotSupportedException {
505 throw new CloneNotSupportedException();
506 }
507
508 /* -- Constructors -- */
509
510 Reference(T referent) {
511 this(referent, null);
512 }
513
514 Reference(T referent, ReferenceQueue<? super T> queue) {
515 if (referent != null) {
516 Objects.requireIdentity(referent);
517 }
518 this.referent = referent;
519 this.queue = (queue == null) ? ReferenceQueue.NULL : queue;
520 }
521
522 /**
523 * Ensures that the object referenced by the given reference remains
524 * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
525 * regardless of any prior actions of the program that might otherwise cause
526 * the object to become unreachable; thus, the referenced object is not
527 * reclaimable by garbage collection at least until after the invocation of
528 * this method. Invocation of this method does not itself initiate garbage
529 * collection or finalization.
530 *
531 * <p> This method establishes an ordering for <em>strong reachability</em>
532 * with respect to garbage collection. It controls relations that are
533 * otherwise only implicit in a program -- the reachability conditions
534 * triggering garbage collection. This method is designed for use in
535 * uncommon situations of premature finalization where using
536 * {@code synchronized} blocks or methods, or using other synchronization
537 * facilities are not possible or do not provide the desired control. This
|