/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package java.lang.ref;
/**
* A reference that is cleared when its referent is not strongly reachable and
* there is memory pressure.
*
* <h3>Avoid Soft References for Caching</h3>
* In practice, soft references are inefficient for caching. The runtime doesn't
* have enough information on which references to clear and which to keep. Most
* fatally, it doesn't know what to do when given the choice between clearing a
* soft reference and growing the heap.
*
* <p>The lack of information on the value to your application of each reference
* limits the usefulness of soft references. References that are cleared too
* early cause unnecessary work; those that are cleared too late waste memory.
*
* <p>Most applications should use an {@code android.util.LruCache} instead of
* soft references. LruCache has an effective eviction policy and lets the user
* tune how much memory is allotted.
*
* <h3>Garbage Collection of Soft References</h3>
* When the garbage collector encounters an object {@code obj} that is
* softly-reachable, the following happens:
* <ul>
* <li>A set {@code refs} of references is determined. {@code refs} contains
* the following elements:
* <ul>
* <li>All soft references pointing to {@code obj}.</li>
* <li>All soft references pointing to objects from which {@code obj} is
* strongly reachable.</li>
* </ul>
* </li>
* <li>All references in {@code refs} are atomically cleared.</li>
* <li>At the same time or some time in the future, all references in {@code
* refs} will be enqueued with their corresponding reference queues, if
* any.</li>
* </ul>
* The system may delay clearing and enqueueing soft references, yet all {@code
* SoftReference}s pointing to softly reachable objects will be cleared before
* the runtime throws an {@link OutOfMemoryError}.
*
* <p>Unlike a {@code WeakReference}, a {@code SoftReference} will not be
* cleared and enqueued until the runtime must reclaim memory to satisfy an
* allocation.
*/
public class SoftReference<T> extends Reference<T> {
/**
* Constructs a new soft reference to the given referent. The newly created
* reference is not registered with any reference queue.
*
* @param r the referent to track
*/
public SoftReference(T r) {
super(r, null);
}
/**
* Constructs a new soft reference to the given referent. The newly created
* reference is registered with the given reference queue.
*
* @param r the referent to track
* @param q the queue to register to the reference object with. A null value
* results in a weak reference that is not associated with any
* queue.
*/
public SoftReference(T r, ReferenceQueue<? super T> q) {
super(r, q);
}
}