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 33 package java.lang.ref; 34 35 /** 36 * Provides an abstract class which describes behavior common to all reference 37 * objects. It is not possible to create immediate subclasses of 38 * {@code Reference} in addition to the ones provided by this package. It is 39 * also not desirable to do so, since references require very close cooperation 40 * with the system's garbage collector. The existing, specialized reference 41 * classes should be used instead. 42 */ 43 public abstract class Reference<T> { 44 45 /** 46 * The object to which this reference refers. 47 * VM requirement: this field <em>must</em> be called "referent" 48 * and be an object. 49 */ 50 volatile T referent; 51 52 /** 53 * If non-null, the queue on which this reference will be enqueued 54 * when the referent is appropriately reachable. 55 * VM requirement: this field <em>must</em> be called "queue" 56 * and be a java.lang.ref.ReferenceQueue. 57 */ 58 volatile ReferenceQueue<? super T> queue; 59 60 /** 61 * Used internally by java.lang.ref.ReferenceQueue. 62 * VM requirement: this field <em>must</em> be called "queueNext" 63 * and be a java.lang.ref.Reference. 64 */ 65 @SuppressWarnings("unchecked") 66 volatile Reference queueNext; 67 68 /** 69 * Used internally by the VM. This field forms a circular and 70 * singly linked list of reference objects discovered by the 71 * garbage collector and awaiting processing by the reference 72 * queue thread. 73 * 74 * @hide 75 */ 76 public volatile Reference<?> pendingNext; 77 78 /** 79 * Constructs a new instance of this class. 80 */ Reference()81 Reference() { 82 } 83 Reference(T r, ReferenceQueue<? super T> q)84 Reference(T r, ReferenceQueue<? super T> q) { 85 referent = r; 86 queue = q; 87 } 88 89 /** 90 * Makes the referent {@code null}. This does not force the reference 91 * object to be enqueued. 92 */ clear()93 public void clear() { 94 referent = null; 95 } 96 97 /** 98 * Adds an object to its reference queue. 99 * 100 * @return {@code true} if this call has caused the {@code Reference} to 101 * become enqueued, or {@code false} otherwise 102 * 103 * @hide 104 */ enqueueInternal()105 public final synchronized boolean enqueueInternal() { 106 if (queue != null && queueNext == null) { 107 queue.enqueue(this); 108 queue = null; 109 return true; 110 } 111 return false; 112 } 113 114 /** 115 * Forces the reference object to be enqueued if it has been associated with 116 * a queue. 117 * 118 * @return {@code true} if this call has caused the {@code Reference} to 119 * become enqueued, or {@code false} otherwise 120 */ enqueue()121 public boolean enqueue() { 122 return enqueueInternal(); 123 } 124 125 /** 126 * Returns the referent of the reference object. 127 * 128 * @return the referent to which reference refers, or {@code null} if the 129 * object has been cleared. 130 */ get()131 public T get() { 132 return referent; 133 } 134 135 /** 136 * Checks whether the reference object has been enqueued. 137 * 138 * @return {@code true} if the {@code Reference} has been enqueued, {@code 139 * false} otherwise 140 */ isEnqueued()141 public boolean isEnqueued() { 142 return queueNext != null; 143 } 144 145 } 146