1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 package java.lang.ref; 28 29 30 /** 31 * Abstract base class for reference objects. This class defines the 32 * operations common to all reference objects. Because reference objects are 33 * implemented in close cooperation with the garbage collector, this class may 34 * not be subclassed directly. 35 * 36 * @author Mark Reinhold 37 * @since 1.2 38 */ 39 40 public abstract class Reference<T> { 41 /** 42 * Forces JNI path. 43 * If GC is not in progress (ie: not going through slow path), the referent 44 * can be quickly returned through intrinsic without passing through JNI. 45 * This flag forces the JNI path so that it can be tested and benchmarked. 46 */ 47 private static boolean disableIntrinsic = false; 48 49 /** 50 * Slow path flag for the reference processor. 51 * Used by the reference processor to determine whether or not the referent 52 * can be immediately returned. Because the referent might get swept during 53 * GC, the slow path, which passes through JNI, must be taken. 54 */ 55 private static boolean slowPathEnabled = false; 56 57 volatile T referent; /* Treated specially by GC */ 58 final ReferenceQueue<? super T> queue; 59 60 /* 61 * This field forms a singly-linked list of reference objects that have 62 * been enqueued. The queueNext field is non-null if and only if this 63 * reference has been enqueued. After this reference has been enqueued and 64 * before it has been removed from its queue, the queueNext field points 65 * to the next reference on the queue. The last reference on a queue 66 * points to itself. Once this reference has been removed from the 67 * reference queue, the queueNext field points to the 68 * ReferenceQueue.sQueueNextUnenqueued sentinel reference object for the 69 * rest of this reference's lifetime. 70 * <p> 71 * Access to the queueNext field is guarded by synchronization on a lock 72 * internal to 'queue'. 73 */ 74 Reference queueNext; 75 76 /** 77 * The pendingNext field is initially set by the GC. After the GC forms a 78 * complete circularly linked list, the list is handed off to the 79 * ReferenceQueueDaemon using the ReferenceQueue.class lock. The 80 * ReferenceQueueDaemon can then read the pendingNext fields without 81 * additional synchronization. 82 */ 83 Reference<?> pendingNext; 84 85 /* -- Referent accessor and setters -- */ 86 87 /** 88 * Returns this reference object's referent. If this reference object has 89 * been cleared, either by the program or by the garbage collector, then 90 * this method returns <code>null</code>. 91 * 92 * @return The object to which this reference refers, or 93 * <code>null</code> if this reference object has been cleared 94 */ get()95 public T get() { 96 return getReferent(); 97 } 98 getReferent()99 private final native T getReferent(); 100 101 /** 102 * Clears this reference object. Invoking this method will not cause this 103 * object to be enqueued. 104 * 105 * <p> This method is invoked only by Java code; when the garbage collector 106 * clears references it does so directly, without invoking this method. 107 */ clear()108 public void clear() { 109 this.referent = null; 110 } 111 112 113 /* -- Queue operations -- */ 114 115 /** 116 * Tells whether or not this reference object has been enqueued, either by 117 * the program or by the garbage collector. If this reference object was 118 * not registered with a queue when it was created, then this method will 119 * always return <code>false</code>. 120 * 121 * @return <code>true</code> if and only if this reference object has 122 * been enqueued 123 */ isEnqueued()124 public boolean isEnqueued() { 125 // Contrary to what the documentation says, this method returns false 126 // after this reference object has been removed from its queue 127 // (b/26647823). ReferenceQueue.isEnqueued preserves this historically 128 // incorrect behavior. 129 return queue != null && queue.isEnqueued(this); 130 } 131 132 /** 133 * Adds this reference object to the queue with which it is registered, 134 * if any. 135 * 136 * <p> This method is invoked only by Java code; when the garbage collector 137 * enqueues references it does so directly, without invoking this method. 138 * 139 * @return <code>true</code> if this reference object was successfully 140 * enqueued; <code>false</code> if it was already enqueued or if 141 * it was not registered with a queue when it was created 142 */ enqueue()143 public boolean enqueue() { 144 return queue != null && queue.enqueue(this); 145 } 146 147 148 /* -- Constructors -- */ 149 Reference(T referent)150 Reference(T referent) { 151 this(referent, null); 152 } 153 Reference(T referent, ReferenceQueue<? super T> queue)154 Reference(T referent, ReferenceQueue<? super T> queue) { 155 this.referent = referent; 156 this.queue = queue; 157 } 158 } 159