| Frames | No Frames |
1: /* java.lang.ref.Reference 2: Copyright (C) 1999, 2002, 2003, 2006 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.lang.ref; 40: 41: /** 42: * This is the base class of all references. A reference allows 43: * refering to an object without preventing the garbage collector to 44: * collect it. The only way to get the referred object is via the 45: * <code>get()</code>-method. This method will return 46: * <code>null</code> if the object was collected. <br> 47: * 48: * A reference may be registered with a queue. When a referred 49: * element gets collected the reference will be put on the queue, so 50: * that you will be notified. <br> 51: * 52: * There are currently three types of references: soft reference, 53: * weak reference and phantom reference. <br> 54: * 55: * Soft references will be cleared if the garbage collector is told 56: * to free some memory and there are no unreferenced or weakly referenced 57: * objects. It is useful for caches. <br> 58: * 59: * Weak references will be cleared as soon as the garbage collector 60: * determines that the refered object is only weakly reachable. They 61: * are useful as keys in hashtables (see <code>WeakHashtable</code>) as 62: * you get notified when nobody has the key anymore. 63: * 64: * Phantom references don't prevent finalization. If an object is only 65: * phantom reachable, it will be finalized, and the reference will be 66: * enqueued, but not cleared. Since you mustn't access an finalized 67: * object, the <code>get</code> method of a phantom reference will never 68: * work. It is useful to keep track, when an object is finalized. 69: * 70: * @author Jochen Hoenicke 71: * @see java.util.WeakHashtable 72: */ 73: public abstract class Reference<T> 74: { 75: /** 76: * The underlying object. This field is handled in a special way by 77: * the garbage collector. 78: * GCJ LOCAL: 79: * This is a RawData because it must be disguised from the GC. 80: * END GCJ LOCAL 81: */ 82: gnu.gcj.RawData referent; 83: 84: /** 85: * This is like REFERENT but is not scanned by the GC. We keep a 86: * copy around so that we can clean up our internal data structure 87: * even after clear() is called. 88: * GCJ LOCAL: 89: * This field doesn't exist in Classpath. 90: * END GCJ LOCAL 91: */ 92: gnu.gcj.RawData copy; 93: 94: /** 95: * Set to true if {@link #clear()} is called. 96: * GCJ LOCAL: 97: * This field doesn't exist in Classpath. It is used internally in 98: * natReference.cc, which enqueues the reference unless it is true 99: * (has been cleared). 100: * END GCJ LOCAL 101: */ 102: boolean cleared = false; 103: 104: /** 105: * The queue this reference is registered on. This is null, if this 106: * wasn't registered to any queue or reference was already enqueued. 107: */ 108: ReferenceQueue<? super T> queue; 109: 110: /** 111: * Link to the next entry on the queue. If this is null, this 112: * reference is not enqueued. Otherwise it points to the next 113: * reference. The last reference on a queue will point to itself 114: * (not to null, that value is used to mark a not enqueued 115: * reference). 116: */ 117: Reference nextOnQueue; 118: 119: /** 120: * This lock should be taken by the garbage collector, before 121: * determining reachability. It will prevent the get()-method to 122: * return the reference so that reachability doesn't change. 123: */ 124: static Object lock = new Object(); 125: 126: /** 127: * Creates a new reference that is not registered to any queue. 128: * Since it is package private, it is not possible to overload this 129: * class in a different package. 130: * @param referent the object we refer to. 131: */ 132: Reference(T ref) 133: { 134: create (ref); 135: } 136: 137: /** 138: * Creates a reference that is registered to a queue. Since this is 139: * package private, it is not possible to overload this class in a 140: * different package. 141: * @param referent the object we refer to. 142: * @param q the reference queue to register on. 143: * @exception NullPointerException if q is null. 144: */ 145: Reference(T ref, ReferenceQueue<? super T> q) 146: { 147: if (q == null) 148: throw new NullPointerException(); 149: queue = q; 150: create (ref); 151: } 152: 153: /** 154: * Notifies the VM that a new Reference has been created. 155: */ 156: private native void create (T o); 157: 158: /** 159: * Returns the object, this reference refers to. 160: * @return the object, this reference refers to, or null if the 161: * reference was cleared. 162: */ 163: public native T get(); 164: 165: /** 166: * Clears the reference, so that it doesn't refer to its object 167: * anymore. For soft and weak references this is called by the 168: * garbage collector. For phantom references you should call 169: * this when enqueuing the reference. 170: */ 171: public void clear() 172: { 173: // Must synchronize so changes are visible in finalizer thread. 174: synchronized (lock) 175: { 176: referent = null; 177: cleared = true; 178: } 179: } 180: 181: /** 182: * Tells if the object is enqueued on a reference queue. 183: * @return true if it is enqueued, false otherwise. 184: */ 185: public boolean isEnqueued() 186: { 187: return nextOnQueue != null; 188: } 189: 190: /** 191: * Enqueue an object on a reference queue. This is normally executed 192: * by the garbage collector. 193: */ 194: public boolean enqueue() 195: { 196: if (queue != null && nextOnQueue == null) 197: { 198: queue.enqueue(this); 199: queue = null; 200: return true; 201: } 202: return false; 203: } 204: }