72 *
73 * Enqueued: queue = ReferenceQueue.ENQUEUED; next = Following instance
74 * in queue, or this if at end of list.
75 *
76 * Inactive: queue = ReferenceQueue.NULL; next = this.
77 *
78 * With this scheme the collector need only examine the next field in order
79 * to determine whether a Reference instance requires special treatment: If
80 * the next field is null then the instance is active; if it is non-null,
81 * then the collector should treat the instance normally.
82 *
83 * To ensure that a concurrent collector can discover active Reference
84 * objects without interfering with application threads that may apply
85 * the enqueue() method to those objects, collectors should link
86 * discovered objects through the discovered field. The discovered
87 * field is also used for linking Reference objects in the pending list.
88 */
89
90 private T referent; /* Treated specially by GC */
91
92 ReferenceQueue<? super T> queue;
93
94 /* When active: NULL
95 * pending: this
96 * Enqueued: next reference in queue (or this if last)
97 * Inactive: this
98 */
99 Reference next;
100
101 /* When active: next element in a discovered reference list maintained by GC (or this if last)
102 * pending: next element in the pending list (or null if last)
103 * otherwise: NULL
104 */
105 transient private Reference<T> discovered; /* used by VM */
106
107
108 /* Object used to synchronize with the garbage collector. The collector
109 * must acquire this lock at the beginning of each collection cycle. It is
110 * therefore critical that any code holding this lock complete as quickly
111 * as possible, allocate no new objects, and avoid calling user code.
112 */
208 * <p> This method is invoked only by Java code; when the garbage collector
209 * clears references it does so directly, without invoking this method.
210 */
211 public void clear() {
212 this.referent = null;
213 }
214
215
216 /* -- Queue operations -- */
217
218 /**
219 * Tells whether or not this reference object has been enqueued, either by
220 * the program or by the garbage collector. If this reference object was
221 * not registered with a queue when it was created, then this method will
222 * always return <code>false</code>.
223 *
224 * @return <code>true</code> if and only if this reference object has
225 * been enqueued
226 */
227 public boolean isEnqueued() {
228 synchronized (this) {
229 return (this.next != null && this.queue == ReferenceQueue.ENQUEUED);
230 }
231 }
232
233 /**
234 * Adds this reference object to the queue with which it is registered,
235 * if any.
236 *
237 * <p> This method is invoked only by Java code; when the garbage collector
238 * enqueues references it does so directly, without invoking this method.
239 *
240 * @return <code>true</code> if this reference object was successfully
241 * enqueued; <code>false</code> if it was already enqueued or if
242 * it was not registered with a queue when it was created
243 */
244 public boolean enqueue() {
245 return this.queue.enqueue(this);
246 }
247
248
249 /* -- Constructors -- */
250
|
72 *
73 * Enqueued: queue = ReferenceQueue.ENQUEUED; next = Following instance
74 * in queue, or this if at end of list.
75 *
76 * Inactive: queue = ReferenceQueue.NULL; next = this.
77 *
78 * With this scheme the collector need only examine the next field in order
79 * to determine whether a Reference instance requires special treatment: If
80 * the next field is null then the instance is active; if it is non-null,
81 * then the collector should treat the instance normally.
82 *
83 * To ensure that a concurrent collector can discover active Reference
84 * objects without interfering with application threads that may apply
85 * the enqueue() method to those objects, collectors should link
86 * discovered objects through the discovered field. The discovered
87 * field is also used for linking Reference objects in the pending list.
88 */
89
90 private T referent; /* Treated specially by GC */
91
92 volatile ReferenceQueue<? super T> queue;
93
94 /* When active: NULL
95 * pending: this
96 * Enqueued: next reference in queue (or this if last)
97 * Inactive: this
98 */
99 Reference next;
100
101 /* When active: next element in a discovered reference list maintained by GC (or this if last)
102 * pending: next element in the pending list (or null if last)
103 * otherwise: NULL
104 */
105 transient private Reference<T> discovered; /* used by VM */
106
107
108 /* Object used to synchronize with the garbage collector. The collector
109 * must acquire this lock at the beginning of each collection cycle. It is
110 * therefore critical that any code holding this lock complete as quickly
111 * as possible, allocate no new objects, and avoid calling user code.
112 */
208 * <p> This method is invoked only by Java code; when the garbage collector
209 * clears references it does so directly, without invoking this method.
210 */
211 public void clear() {
212 this.referent = null;
213 }
214
215
216 /* -- Queue operations -- */
217
218 /**
219 * Tells whether or not this reference object has been enqueued, either by
220 * the program or by the garbage collector. If this reference object was
221 * not registered with a queue when it was created, then this method will
222 * always return <code>false</code>.
223 *
224 * @return <code>true</code> if and only if this reference object has
225 * been enqueued
226 */
227 public boolean isEnqueued() {
228 return (this.queue == ReferenceQueue.ENQUEUED);
229 }
230
231 /**
232 * Adds this reference object to the queue with which it is registered,
233 * if any.
234 *
235 * <p> This method is invoked only by Java code; when the garbage collector
236 * enqueues references it does so directly, without invoking this method.
237 *
238 * @return <code>true</code> if this reference object was successfully
239 * enqueued; <code>false</code> if it was already enqueued or if
240 * it was not registered with a queue when it was created
241 */
242 public boolean enqueue() {
243 return this.queue.enqueue(this);
244 }
245
246
247 /* -- Constructors -- */
248
|