46  * scheduling post-mortem cleanup actions.
  47  *
  48  * <p> Each reference-object type is implemented by a subclass of the
  49  * abstract base {@link java.lang.ref.Reference} class.
  50  * An instance of one of these subclasses encapsulates a single
  51  * reference to a particular object, called the <em>referent</em>.
  52  * Every reference object provides methods for getting and clearing
  53  * the reference.  Aside from the clearing operation reference objects
  54  * are otherwise immutable, so no {@code set} operation is
  55  * provided.  A program may further subclass these subclasses, adding
  56  * whatever fields and methods are required for its purposes, or it
  57  * may use these subclasses without change.
  58  *
  59  * <h3>Notification</h3>
  60  *
  61  * A program may request to be notified of changes in an object's
  62  * reachability by <em>registering</em> an appropriate reference
  63  * object with a <em>reference queue</em> at the time the reference
  64  * object is created.  Some time after the garbage collector
  65  * determines that the reachability of the referent has changed to the
  66  * value corresponding to the type of the reference, it will add the
  67  * reference to the associated queue.  At this point, the reference is
  68  * considered to be <em>enqueued</em>.  The program may remove
  69  * references from a queue either by polling or by blocking until a
  70  * reference becomes available.  Reference queues are implemented by
  71  * the {@link java.lang.ref.ReferenceQueue} class.
  72  *
  73  * <p> The relationship between a registered reference object and its
  74  * queue is one-sided.  That is, a queue does not keep track of the
  75  * references that are registered with it.  If a registered reference
  76  * becomes unreachable itself, then it will never be enqueued.  It is
  77  * the responsibility of the program using reference objects to ensure
  78  * that the objects remain reachable for as long as the program is
  79  * interested in their referents.
  80  *
  81  * <p> While some programs will choose to dedicate a thread to
  82  * removing reference objects from one or more queues and processing
  83  * them, this is by no means necessary.  A tactic that often works
  84  * well is to examine a reference queue in the course of performing
  85  * some other fairly-frequent action.  For example, a hashtable that
  86  * uses weak references to implement weak keys could poll its
  87  * reference queue each time the table is accessed.  This is how the
  88  * {@link java.util.WeakHashMap} class works.  Because
  89  * the {@link java.lang.ref.ReferenceQueue#poll
  90  * ReferenceQueue.poll} method simply checks an internal data
  91  * structure, this check will add little overhead to the hashtable
  92  * access methods.
  93  *
  94  * <h3>Automatically-cleared references</h3>
  95  *
  96  * Soft and weak references are automatically cleared by the collector
  97  * before being added to the queues with which they are registered, if any,
  98  * hence they need not be registered with a queue in order to be useful.
  99  * Phantom references, by contrast, do not allow their referents to be
 100  * retrieved, so they must be registered with a queue.
 101  *
 102  * <a name="reachability"></a>
 103  * <h3>Reachability</h3>
 104  *
 105  * Going from strongest to weakest, the different levels of
 106  * reachability reflect the life cycle of an object.  They are
 107  * operationally defined as follows:
 108  *
 109  * <ul>
 110  *
 111  * <li> An object is <em>strongly reachable</em> if it can be reached
 112  * by some thread without traversing any reference objects.  A
 113  * newly-created object is strongly reachable by the thread that
 114  * created it.
 115  *
 116  * <li> An object is <em>softly reachable</em> if it is not strongly
 117  * reachable but can be reached by traversing a soft reference.
 118  *
 119  * <li> An object is <em>weakly reachable</em> if it is neither
 120  * strongly nor softly reachable but can be reached by traversing a

  46  * scheduling post-mortem cleanup actions.
  47  *
  48  * <p> Each reference-object type is implemented by a subclass of the
  49  * abstract base {@link java.lang.ref.Reference} class.
  50  * An instance of one of these subclasses encapsulates a single
  51  * reference to a particular object, called the <em>referent</em>.
  52  * Every reference object provides methods for getting and clearing
  53  * the reference.  Aside from the clearing operation reference objects
  54  * are otherwise immutable, so no {@code set} operation is
  55  * provided.  A program may further subclass these subclasses, adding
  56  * whatever fields and methods are required for its purposes, or it
  57  * may use these subclasses without change.
  58  *
  59  * <h3>Notification</h3>
  60  *
  61  * A program may request to be notified of changes in an object's
  62  * reachability by <em>registering</em> an appropriate reference
  63  * object with a <em>reference queue</em> at the time the reference
  64  * object is created.  Some time after the garbage collector
  65  * determines that the reachability of the referent has changed to the
  66  * value corresponding to the type of the reference, it will clear the
  67  * reference and add it to the associated queue.  At this point, the
  68  * reference is considered to be <em>enqueued</em>.  The program may remove
  69  * references from a queue either by polling or by blocking until a
  70  * reference becomes available.  Reference queues are implemented by
  71  * the {@link java.lang.ref.ReferenceQueue} class.
  72  *
  73  * <p> The relationship between a registered reference object and its
  74  * queue is one-sided.  That is, a queue does not keep track of the
  75  * references that are registered with it.  If a registered reference
  76  * becomes unreachable itself, then it will never be enqueued.  It is
  77  * the responsibility of the program using reference objects to ensure
  78  * that the objects remain reachable for as long as the program is
  79  * interested in their referents.
  80  *
  81  * <p> While some programs will choose to dedicate a thread to
  82  * removing reference objects from one or more queues and processing
  83  * them, this is by no means necessary.  A tactic that often works
  84  * well is to examine a reference queue in the course of performing
  85  * some other fairly-frequent action.  For example, a hashtable that
  86  * uses weak references to implement weak keys could poll its
  87  * reference queue each time the table is accessed.  This is how the
  88  * {@link java.util.WeakHashMap} class works.  Because
  89  * the {@link java.lang.ref.ReferenceQueue#poll
  90  * ReferenceQueue.poll} method simply checks an internal data
  91  * structure, this check will add little overhead to the hashtable
  92  * access methods.








  93  *
  94  * <a name="reachability"></a>
  95  * <h3>Reachability</h3>
  96  *
  97  * Going from strongest to weakest, the different levels of
  98  * reachability reflect the life cycle of an object.  They are
  99  * operationally defined as follows:
 100  *
 101  * <ul>
 102  *
 103  * <li> An object is <em>strongly reachable</em> if it can be reached
 104  * by some thread without traversing any reference objects.  A
 105  * newly-created object is strongly reachable by the thread that
 106  * created it.
 107  *
 108  * <li> An object is <em>softly reachable</em> if it is not strongly
 109  * reachable but can be reached by traversing a soft reference.
 110  *
 111  * <li> An object is <em>weakly reachable</em> if it is neither
 112  * strongly nor softly reachable but can be reached by traversing a