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 @SuppressWarnings("unchecked") 59 volatile ReferenceQueue queue; 60 61 /** 62 * Used internally by java.lang.ref.ReferenceQueue. 63 * VM requirement: this field <em>must</em> be called "queueNext" 64 * and be a java.lang.ref.Reference. 65 */ 66 @SuppressWarnings("unchecked") 67 volatile Reference queueNext; 68 69 /** 70 * Used internally by the VM. This field forms a circular and 71 * singly linked list of reference objects discovered by the 72 * garbage collector and awaiting processing by the reference 73 * queue thread. 74 * 75 * @hide 76 */ 77 public volatile Reference<?> pendingNext; 78 79 /** 80 * Constructs a new instance of this class. 81 */ Reference()82 Reference() { 83 } 84 Reference(T r, ReferenceQueue q)85 Reference(T r, ReferenceQueue q) { 86 referent = r; 87 queue = q; 88 } 89 90 /** 91 * Makes the referent {@code null}. This does not force the reference 92 * object to be enqueued. 93 */ clear()94 public void clear() { 95 referent = null; 96 } 97 98 /** 99 * Adds an object to its reference queue. 100 * 101 * @return {@code true} if this call has caused the {@code Reference} to 102 * become enqueued, or {@code false} otherwise 103 * 104 * @hide 105 */ enqueueInternal()106 public final synchronized boolean enqueueInternal() { 107 if (queue != null && queueNext == null) { 108 queue.enqueue(this); 109 queue = null; 110 return true; 111 } 112 return false; 113 } 114 115 /** 116 * Forces the reference object to be enqueued if it has been associated with 117 * a queue. 118 * 119 * @return {@code true} if this call has caused the {@code Reference} to 120 * become enqueued, or {@code false} otherwise 121 */ enqueue()122 public boolean enqueue() { 123 return enqueueInternal(); 124 } 125 126 /** 127 * Returns the referent of the reference object. 128 * 129 * @return the referent to which reference refers, or {@code null} if the 130 * object has been cleared. 131 */ get()132 public T get() { 133 return referent; 134 } 135 136 /** 137 * Checks whether the reference object has been enqueued. 138 * 139 * @return {@code true} if the {@code Reference} has been enqueued, {@code 140 * false} otherwise 141 */ isEnqueued()142 public boolean isEnqueued() { 143 return queueNext != null; 144 } 145 146 } 147