1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 /* 18 * Copyright (C) 2008 The Android Open Source Project 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); 21 * you may not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, 28 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 package java.lang.ref; 34 35 /** 36 * Provides an abstract class which describes behavior common to all reference 37 * objects. It is not possible to create immediate subclasses of 38 * {@code Reference} in addition to the ones provided by this package. It is 39 * also not desirable to do so, since references require very close cooperation 40 * with the system's garbage collector. The existing, specialized reference 41 * classes should be used instead. 42 * 43 * <p>Three different type of references exist, each being weaker than the preceding one: 44 * {@link java.lang.ref.SoftReference}, {@link java.lang.ref.WeakReference}, and 45 * {@link java.lang.ref.PhantomReference}. "Weakness" here means that less restrictions are 46 * being imposed on the garbage collector as to when it is allowed to 47 * actually garbage-collect the referenced object. 48 * 49 * <p>In order to use reference objects properly it is important to understand 50 * the different types of reachability that trigger their clearing and 51 * enqueueing. The following table lists these, from strongest to weakest. 52 * For each row, an object is said to have the reachability on the left side 53 * if (and only if) it fulfills all of the requirements on the right side. In 54 * all rows, consider the <em>root set</em> to be a set of references that 55 * are "resistant" to garbage collection (that is, running threads, method 56 * parameters, local variables, static fields and the like). 57 * 58 * <p><table> 59 * <tr> 60 * <td>Strongly reachable</td> 61 * <td> <ul> 62 * <li>There exists at least one path from the root set to the object that does not traverse any 63 * instance of a {@code java.lang.ref.Reference} subclass. 64 * </li> 65 * </ul> </td> 66 * </tr> 67 * 68 * <tr> 69 * <td>Softly reachable</td> 70 * <td> <ul> 71 * <li>The object is not strongly reachable.</li> 72 * <li>There exists at least one path from the root set to the object that does traverse 73 * a {@code java.lang.ref.SoftReference} instance, but no {@code java.lang.ref.WeakReference} 74 * or {@code java.lang.ref.PhantomReference} instances.</li> 75 * </ul> </td> 76 * </tr> 77 * 78 * <tr> 79 * <td>Weakly reachable</td> 80 * <td> <ul> 81 * <li>The object is neither strongly nor softly reachable.</li> 82 * <li>There exists at least one path from the root set to the object that does traverse a 83 * {@code java.lang.ref.WeakReference} instance, but no {@code java.lang.ref.PhantomReference} 84 * instances.</li> 85 * </ul> </td> 86 * </tr> 87 * 88 * <tr> 89 * <td>Phantom-reachable</td> 90 * <td> <ul> 91 * <li>The object is neither strongly, softly, nor weakly reachable.</li> 92 * <li>The object is referenced by a {@code java.lang.ref.PhantomReference} instance.</li> 93 * <li>The object has already been finalized.</li> 94 * </ul> </td> 95 * </tr> 96 * </table> 97 */ 98 public abstract class Reference<T> { 99 100 /** 101 * The object to which this reference refers. 102 * VM requirement: this field <em>must</em> be called "referent" 103 * and be an object. 104 */ 105 volatile T referent; 106 107 /** 108 * If non-null, the queue on which this reference will be enqueued 109 * when the referent is appropriately reachable. 110 * VM requirement: this field <em>must</em> be called "queue" 111 * and be a java.lang.ref.ReferenceQueue. 112 */ 113 volatile ReferenceQueue<? super T> queue; 114 115 /** 116 * Used internally by java.lang.ref.ReferenceQueue. 117 * VM requirement: this field <em>must</em> be called "queueNext" 118 * and be a java.lang.ref.Reference. 119 */ 120 @SuppressWarnings("unchecked") 121 volatile Reference queueNext; 122 123 /** 124 * Used internally by the VM. This field forms a circular and 125 * singly linked list of reference objects discovered by the 126 * garbage collector and awaiting processing by the reference 127 * queue thread. 128 * 129 * @hide 130 */ 131 public volatile Reference<?> pendingNext; 132 133 /** 134 * Constructs a new instance of this class. 135 */ Reference()136 Reference() { 137 } 138 Reference(T r, ReferenceQueue<? super T> q)139 Reference(T r, ReferenceQueue<? super T> q) { 140 referent = r; 141 queue = q; 142 } 143 144 /** 145 * Makes the referent {@code null}. This does not force the reference 146 * object to be enqueued. 147 */ clear()148 public void clear() { 149 referent = null; 150 } 151 152 /** 153 * Adds an object to its reference queue. 154 * 155 * @return {@code true} if this call has caused the {@code Reference} to 156 * become enqueued, or {@code false} otherwise 157 * 158 * @hide 159 */ enqueueInternal()160 public final synchronized boolean enqueueInternal() { 161 if (queue != null && queueNext == null) { 162 queue.enqueue(this); 163 queue = null; 164 return true; 165 } 166 return false; 167 } 168 169 /** 170 * Forces the reference object to be enqueued if it has been associated with 171 * a queue. 172 * 173 * @return {@code true} if this call has caused the {@code Reference} to 174 * become enqueued, or {@code false} otherwise 175 */ enqueue()176 public boolean enqueue() { 177 return enqueueInternal(); 178 } 179 180 /** 181 * Returns the referent of the reference object. 182 * 183 * @return the referent to which reference refers, or {@code null} if the 184 * object has been cleared. 185 */ get()186 public T get() { 187 return referent; 188 } 189 190 /** 191 * Checks whether the reference object has been enqueued. 192 * 193 * @return {@code true} if the {@code Reference} has been enqueued, {@code 194 * false} otherwise 195 */ isEnqueued()196 public boolean isEnqueued() { 197 return queueNext != null; 198 } 199 200 } 201