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