1 /* 2 * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 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 29 /** 30 * Soft reference objects, which are cleared at the discretion of the garbage 31 * collector in response to memory demand. 32 * 33 * <p> Suppose that the garbage collector determines at a certain point in time 34 * that an object is <a href="package-summary.html#reachability">softly 35 * reachable</a>. At that time it may choose to clear atomically all soft 36 * references to that object and all soft references to any other 37 * softly-reachable objects from which that object is reachable through a chain 38 * of strong references. At the same time or at some later time it will 39 * enqueue those newly-cleared soft references that are registered with 40 * reference queues. 41 * 42 * <p> All soft references to softly-reachable objects are guaranteed to have 43 * been cleared before the virtual machine throws an 44 * <code>OutOfMemoryError</code>. Otherwise no constraints are placed upon the 45 * time at which a soft reference will be cleared or the order in which a set 46 * of such references to different objects will be cleared. Virtual machine 47 * implementations are, however, encouraged to bias against clearing 48 * recently-created or recently-used soft references. 49 * 50 * <h3>Avoid Soft References for Caching</h3> 51 * In practice, soft references are inefficient for caching. The runtime doesn't 52 * have enough information on which references to clear and which to keep. Most 53 * fatally, it doesn't know what to do when given the choice between clearing a 54 * soft reference and growing the heap. 55 * 56 * <p>The lack of information on the value to your application of each reference 57 * limits the usefulness of soft references. References that are cleared too 58 * early cause unnecessary work; those that are cleared too late waste memory. 59 * 60 * <p>Most applications should use an {@code android.util.LruCache} instead of 61 * soft references. LruCache has an effective eviction policy and lets the user 62 * tune how much memory is allotted. 63 * 64 * @author Mark Reinhold 65 * @since 1.2 66 */ 67 68 public class SoftReference<T> extends Reference<T> { 69 70 /** 71 * Timestamp clock, updated by the garbage collector 72 */ 73 static private long clock; 74 75 /** 76 * Timestamp updated by each invocation of the get method. The VM may use 77 * this field when selecting soft references to be cleared, but it is not 78 * required to do so. 79 */ 80 private long timestamp; 81 82 /** 83 * Creates a new soft reference that refers to the given object. The new 84 * reference is not registered with any queue. 85 * 86 * @param referent object the new soft reference will refer to 87 */ SoftReference(T referent)88 public SoftReference(T referent) { 89 super(referent); 90 this.timestamp = clock; 91 } 92 93 /** 94 * Creates a new soft reference that refers to the given object and is 95 * registered with the given queue. 96 * 97 * @param referent object the new soft reference will refer to 98 * @param q the queue with which the reference is to be registered, 99 * or <tt>null</tt> if registration is not required 100 * 101 */ SoftReference(T referent, ReferenceQueue<? super T> q)102 public SoftReference(T referent, ReferenceQueue<? super T> q) { 103 super(referent, q); 104 this.timestamp = clock; 105 } 106 107 /** 108 * Returns this reference object's referent. If this reference object has 109 * been cleared, either by the program or by the garbage collector, then 110 * this method returns <code>null</code>. 111 * 112 * @return The object to which this reference refers, or 113 * <code>null</code> if this reference object has been cleared 114 */ get()115 public T get() { 116 T o = super.get(); 117 if (o != null && this.timestamp != clock) 118 this.timestamp = clock; 119 return o; 120 } 121 122 } 123