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 * Implements a soft reference, which is the least-weak of the three types of 37 * references. Once the garbage collector has decided that an object {@code obj} 38 * is softly-reachable, the following 39 * may happen, either immediately or at a later point: 40 * 41 * <ul> 42 * <li> 43 * A set {@code ref} of references is determined. {@code ref} contains the 44 * following elements: 45 * <ul> 46 * <li> 47 * All soft references pointing to {@code obj}. 48 * </li> 49 * <li> 50 * All soft references pointing to objects from which {@code obj} is 51 * strongly reachable. 52 * </li> 53 * </ul> 54 * </li> 55 * <li> 56 * All references in {@code ref} are atomically cleared. 57 * </li> 58 * <li> 59 * At the same time or some time in the future, all references in {@code 60 * ref} will be enqueued with their corresponding reference queues, if any. 61 * </li> 62 * </ul> 63 * 64 * The system may decide not to clear and enqueue soft references until a later 65 * time, yet all {@code SoftReference}s pointing to softly reachable objects are 66 * guaranteed to be cleared before the VM will throw an {@link 67 * java.lang.OutOfMemoryError}. 68 * 69 * Soft references are useful for caches that should automatically have 70 * their entries removed once they are not referenced any more (from outside), 71 * and there is a need for memory. The difference between a {@code 72 * SoftReference} and a {@code WeakReference} is the point of time at which the 73 * decision is made to clear and enqueue the reference: 74 * 75 * <ul> 76 * <li> 77 * A {@code SoftReference} should be cleared and enqueued <em>as late as 78 * possible</em>, that is, in case the VM is in danger of running out of 79 * memory. 80 * </li> 81 * <li> 82 * A {@code WeakReference} may be cleared and enqueued as soon as is 83 * known to be weakly-referenced. 84 * </li> 85 * </ul> 86 */ 87 public class SoftReference<T> extends Reference<T> { 88 89 /** 90 * Constructs a new soft reference to the given referent. The newly created 91 * reference is not registered with any reference queue. 92 * 93 * @param r the referent to track 94 */ 95 public SoftReference(T r) { 96 super(); 97 referent = r; 98 } 99 100 /** 101 * Constructs a new soft reference to the given referent. The newly created 102 * reference is registered with the given reference queue. 103 * 104 * @param r the referent to track 105 * @param q the queue to register to the reference object with. A null value 106 * results in a weak reference that is not associated with any 107 * queue. 108 */ 109 public SoftReference(T r, ReferenceQueue<? super T> q) { 110 super(); 111 referent = r; 112 queue = q; 113 } 114 } 115
