1f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes/* 2adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Licensed to the Apache Software Foundation (ASF) under one or more 3adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * contributor license agreements. See the NOTICE file distributed with 4adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * this work for additional information regarding copyright ownership. 5adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * The ASF licenses this file to You under the Apache License, Version 2.0 6adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * (the "License"); you may not use this file except in compliance with 7adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * the License. You may obtain a copy of the License at 8f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 9adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 10f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 11adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 12adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 13adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 15adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 16adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 17adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/* 18adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Copyright (C) 2008 The Android Open Source Project 19adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 20adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 21adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * you may not use this file except in compliance with the License. 22adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * You may obtain a copy of the License at 23adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 24adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 25adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * 26adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Unless required by applicable law or agreed to in writing, software 27adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 28adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * See the License for the specific language governing permissions and 30adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * limitations under the License. 31adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 32adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 33adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpackage java.lang.ref; 34adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 35adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project/** 3632c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * A reference that is cleared when its referent is not strongly reachable and 37132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * there is memory pressure. 38f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 39132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <h3>Avoid Soft References for Caching</h3> 40132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * In practice, soft references are inefficient for caching. The runtime doesn't 41132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * have enough information on which references to clear and which to keep. Most 42132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * fatally, it doesn't know what to do when given the choice between clearing a 43132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * soft reference and growing the heap. 44f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 4532c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * <p>The lack of information on the value to your application of each reference 4632c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * limits the usefulness of soft references. References that are cleared too 4732c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * early cause unnecessary work; those that are cleared too late waste memory. 48f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 49132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <p>Most applications should use an {@code android.util.LruCache} instead of 5032c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * soft references. LruCache has an effective eviction policy and lets the user 51132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * tune how much memory is allotted. 52f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 5332c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * <h3>Garbage Collection of Soft References</h3> 54132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * When the garbage collector encounters an object {@code obj} that is 55132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * softly-reachable, the following happens: 56adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * <ul> 5732c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * <li>A set {@code refs} of references is determined. {@code refs} contains 5832c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * the following elements: 59132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <ul> 60132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <li>All soft references pointing to {@code obj}.</li> 61132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <li>All soft references pointing to objects from which {@code obj} is 62132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * strongly reachable.</li> 63132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * </ul> 64adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </li> 6532c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * <li>All references in {@code refs} are atomically cleared.</li> 66132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <li>At the same time or some time in the future, all references in {@code 6732c000e63448fd4f349f211e04c34fc2b3a98559Jesse Wilson * refs} will be enqueued with their corresponding reference queues, if 68132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * any.</li> 69adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * </ul> 70132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * The system may delay clearing and enqueueing soft references, yet all {@code 71132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * SoftReference}s pointing to softly reachable objects will be cleared before 72132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * the runtime throws an {@link OutOfMemoryError}. 73132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * 74132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * <p>Unlike a {@code WeakReference}, a {@code SoftReference} will not be 75132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * cleared and enqueued until the runtime must reclaim memory to satisfy an 76132829c52b75a39c05b5ab06199aeb39b28abc40Jesse Wilson * allocation. 77adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 78adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Projectpublic class SoftReference<T> extends Reference<T> { 79adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project 80adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 81adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Constructs a new soft reference to the given referent. The newly created 82adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * reference is not registered with any reference queue. 83f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 84adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param r the referent to track 85adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 86adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public SoftReference(T r) { 87ba1e5f9b7ffe3a42f1001ece077f566de8231548Carl Shapiro super(r, null); 88adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 89f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 90adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project /** 91adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * Constructs a new soft reference to the given referent. The newly created 92adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * reference is registered with the given reference queue. 93f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 94adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param r the referent to track 95adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * @param q the queue to register to the reference object with. A null value 96adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * results in a weak reference that is not associated with any 97adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project * queue. 98adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project */ 99adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project public SoftReference(T r, ReferenceQueue<? super T> q) { 100ba1e5f9b7ffe3a42f1001ece077f566de8231548Carl Shapiro super(r, q); 101adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project } 102adc854b798c1cfe3bfd4c27d68d5cee38ca617daThe Android Open Source Project} 103