- 01
/* - 02
* @(#)SoftReference.java 1.35 05/11/17 - 03 *
- 04 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- 05 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- 06
*/ - 07
- 08package java.lang.ref;
- 09
- 10
- 11/**
- 12 * Soft reference objects, which are cleared at the discretion of the garbage
- 13 * collector in response to memory demand. Soft references are most often used
- 14 * to implement memory-sensitive caches.
- 15 *
- 16 * <p> Suppose that the garbage collector determines at a certain point in time
- 17 * that an object is <a href="package-summary.html#reachability">softly
- 18 * reachable</a>. At that time it may choose to clear atomically all soft
- 19 * references to that object and all soft references to any other
- 20 * softly-reachable objects from which that object is reachable through a chain
- 21 * of strong references. At the same time or at some later time it will
- 22 * enqueue those newly-cleared soft references that are registered with
- 23 * reference queues.
- 24 *
- 25 * <p> All soft references to softly-reachable objects are guaranteed to have
- 26 * been cleared before the virtual machine throws an
- 27 * <code>OutOfMemoryError</code>. Otherwise no constraints are placed upon the
- 28 * time at which a soft reference will be cleared or the order in which a set
- 29 * of such references to different objects will be cleared. Virtual machine
- 30 * implementations are, however, encouraged to bias against clearing
- 31 * recently-created or recently-used soft references.
- 32 *
- 33 * <p> Direct instances of this class may be used to implement simple caches;
- 34 * this class or derived subclasses may also be used in larger data structures
- 35 * to implement more sophisticated caches. As long as the referent of a soft
- 36 * reference is strongly reachable, that is, is actually in use, the soft
- 37 * reference will not be cleared. Thus a sophisticated cache can, for example,
- 38 * prevent its most recently used entries from being discarded by keeping
- 39 * strong referents to those entries, leaving the remaining entries to be
- 40 * discarded at the discretion of the garbage collector.
- 41 *
- 42 * @version 1.35, 11/17/05
- 43 * @author Mark Reinhold
- 44 * @since 1.2
- 45 */
- 46
- 47public class SoftReference<T> extends Reference<T> {
- 48
- 49 /* Timestamp clock, updated by the garbage collector
- 50 */
- 51 static private long clock;
- 52
- 53 /* Timestamp updated by each invocation of the get method. The VM may use
- 54 * this field when selecting soft references to be cleared, but it is not
- 55 * required to do so.
- 56 */
- 57 private long timestamp;
- 58
- 59 /**
- 60 * Creates a new soft reference that refers to the given object. The new
- 61 * reference is not registered with any queue.
- 62 *
- 63 * @param referent object the new soft reference will refer to
- 64 */
- 65 public SoftReference(T referent) {
- 66 super(referent);
- 67 this.timestamp = clock;
- 68 }
- 69
- 70 /**
- 71 * Creates a new soft reference that refers to the given object and is
- 72 * registered with the given queue.
- 73 *
- 74 * @param referent object the new soft reference will refer to
- 75 * @param q the queue with which the reference is to be registered,
- 76 * or <tt>null</tt> if registration is not required
- 77 *
- 78 */
- 79 public SoftReference(T referent, ReferenceQueue<? super T> q) {
- 80 super(referent, q);
- 81 this.timestamp = clock;
- 82 }
- 83
- 84 /**
- 85 * Returns this reference object's referent. If this reference object has
- 86 * been cleared, either by the program or by the garbage collector, then
- 87 * this method returns <code>null</code>.
- 88 *
- 89 * @return The object to which this reference refers, or
- 90 * <code>null</code> if this reference object has been cleared
- 91 */
- 92 public T get() {
- 93 T o = super.get();
- 94 if (o != null) this.timestamp = clock;
- 95 return o;
- 96 }
- 97
- 98}
