KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > ref > Reference


1 /*
2  * @(#)Reference.java 1.41 04/04/20
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.lang.ref;
9
10 import sun.misc.Cleaner;
11
12
13 /**
14  * Abstract base class for reference objects. This class defines the
15  * operations common to all reference objects. Because reference objects are
16  * implemented in close cooperation with the garbage collector, this class may
17  * not be subclassed directly.
18  *
19  * @version 1.41, 04/20/04
20  * @author Mark Reinhold
21  * @since 1.2
22  */
23
24 public abstract class Reference<T> {
25
26     /* A Reference instance is in one of four possible internal states:
27      *
28      * Active: Subject to special treatment by the garbage collector. Some
29      * time after the collector detects that the reachability of the
30      * referent has changed to the appropriate state, it changes the
31      * instance's state to either Pending or Inactive, depending upon
32      * whether or not the instance was registered with a queue when it was
33      * created. In the former case it also adds the instance to the
34      * pending-Reference list. Newly-created instances are Active.
35      *
36      * Pending: An element of the pending-Reference list, waiting to be
37      * enqueued by the Reference-handler thread. Unregistered instances
38      * are never in this state.
39      *
40      * Enqueued: An element of the queue with which the instance was
41      * registered when it was created. When an instance is removed from
42      * its ReferenceQueue, it is made Inactive. Unregistered instances are
43      * never in this state.
44      *
45      * Inactive: Nothing more to do. Once an instance becomes Inactive its
46      * state will never change again.
47      *
48      * The state is encoded in the queue and next fields as follows:
49      *
50      * Active: queue = ReferenceQueue with which instance is registered, or
51      * ReferenceQueue.NULL if it was not registered with a queue; next =
52      * null.
53      *
54      * Pending: queue = ReferenceQueue with which instance is registered;
55      * next = Following instance in queue, or this if at end of list.
56      *
57      * Enqueued: queue = ReferenceQueue.ENQUEUED; next = Following instance
58      * in queue, or this if at end of list.
59      *
60      * Inactive: queue = ReferenceQueue.NULL; next = this.
61      *
62      * With this scheme the collector need only examine the next field in order
63      * to determine whether a Reference instance requires special treatment: If
64      * the next field is null then the instance is active; if it is non-null,
65      * then the collector should treat the instance normally.
66      *
67      * To ensure that concurrent collector can discover active Reference
68      * objects without interfering with application threads that may apply
69      * the enqueue() method to those objects, collectors should link
70      * discovered objects through the discovered field.
71      */
72
73     private T referent; /* Treated specially by GC */
74
75     ReferenceQueue JavaDoc<? super T> queue;
76
77     Reference JavaDoc next;
78     transient private Reference JavaDoc<T> discovered; /* used by VM */
79
80
81     /* Object used to synchronize with the garbage collector. The collector
82      * must acquire this lock at the beginning of each collection cycle. It is
83      * therefore critical that any code holding this lock complete as quickly
84      * as possible, allocate no new objects, and avoid calling user code.
85      */
86     static private class Lock { };
87     private static Lock lock = new Lock();
88
89
90     /* List of References waiting to be enqueued. The collector adds
91      * References to this list, while the Reference-handler thread removes
92      * them. This list is protected by the above lock object.
93      */
94     private static Reference JavaDoc pending = null;
95
96     /* High-priority thread to enqueue pending References
97      */
98     private static class ReferenceHandler extends Thread JavaDoc {
99
100     ReferenceHandler(ThreadGroup JavaDoc g, String JavaDoc name) {
101         super(g, name);
102     }
103
104     public void run() {
105         for (;;) {
106
107         Reference JavaDoc r;
108         synchronized (lock) {
109             if (pending != null) {
110             r = pending;
111             Reference JavaDoc rn = r.next;
112             pending = (rn == r) ? null : rn;
113             r.next = r;
114             } else {
115             try {
116                 lock.wait();
117             } catch (InterruptedException JavaDoc x) { }
118             continue;
119             }
120         }
121
122         // Fast path for cleaners
123 if (r instanceof Cleaner) {
124             ((Cleaner)r).clean();
125             continue;
126         }
127
128         ReferenceQueue JavaDoc q = r.queue;
129         if (q != ReferenceQueue.NULL) q.enqueue(r);
130         }
131     }
132     }
133
134     static {
135     ThreadGroup JavaDoc tg = Thread.currentThread().getThreadGroup();
136     for (ThreadGroup JavaDoc tgn = tg;
137          tgn != null;
138          tg = tgn, tgn = tg.getParent());
139     Thread JavaDoc handler = new ReferenceHandler(tg, "Reference Handler");
140     /* If there were a special system-only priority greater than
141      * MAX_PRIORITY, it would be used here
142      */
143     handler.setPriority(Thread.MAX_PRIORITY);
144     handler.setDaemon(true);
145     handler.start();
146     }
147
148
149     /* -- Referent accessor and setters -- */
150
151     /**
152      * Returns this reference object's referent. If this reference object has
153      * been cleared, either by the program or by the garbage collector, then
154      * this method returns <code>null</code>.
155      *
156      * @return The object to which this reference refers, or
157      * <code>null</code> if this reference object has been cleared
158      */
159     public T get() {
160     return this.referent;
161     }
162
163     /**
164      * Clears this reference object. Invoking this method will not cause this
165      * object to be enqueued.
166      */
167     public void clear() {
168     this.referent = null;
169     }
170
171
172     /* -- Queue operations -- */
173
174     /**
175      * Tells whether or not this reference object has been enqueued, either by
176      * the program or by the garbage collector. If this reference object was
177      * not registered with a queue when it was created, then this method will
178      * always return <code>false</code>.
179      *
180      * @return <code>true</code> if and only if this reference object has
181      * been enqueued
182      */
183     public boolean isEnqueued() {
184     /* In terms of the internal states, this predicate actually tests
185        whether the instance is either Pending or Enqueued */
186     synchronized (this) {
187         return (this.queue != ReferenceQueue.NULL) && (this.next != null);
188     }
189     }
190
191     /**
192      * Adds this reference object to the queue with which it is registered,
193      * if any.
194      *
195      * @return <code>true</code> if this reference object was successfully
196      * enqueued; <code>false</code> if it was already enqueued or if
197      * it was not registered with a queue when it was created
198      */
199     public boolean enqueue() {
200     return this.queue.enqueue(this);
201     }
202
203
204     /* -- Constructors -- */
205
206     Reference(T referent) {
207     this(referent, null);
208     }
209
210     Reference(T referent, ReferenceQueue JavaDoc<? super T> queue) {
211     this.referent = referent;
212     this.queue = (queue == null) ? ReferenceQueue.NULL : queue;
213     }
214
215 }
216
Popular Tags