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