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
33package 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 */
87public 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