< prev index next >

src/java.base/share/classes/java/lang/ref/Reference.java

Print this page
rev 50108 : [mq]: tschatzl_1


  59      * referent = null; discovered = next element in pending-Reference list.
  60      *
  61      * Inactive: Neither Active nor Pending.
  62      * referent = null.
  63      *
  64      * Registered: Associated with a queue when created, and not yet added to
  65      * the queue.
  66      * queue = the associated queue.
  67      *
  68      * Enqueued: Added to the associated queue, and not yet removed.
  69      * queue = ReferenceQueue.ENQUEUE; next = next entry in list, or this to
  70      * indicate end of list.
  71      *
  72      * Dequeued: Added to the associated queue and then removed.
  73      * queue = ReferenceQueue.NULL; next = this.
  74      *
  75      * Unregistered: Not associated with a queue when created.
  76      * queue = ReferenceQueue.NULL.
  77      *
  78      * The collector only needs to examine the referent field and the
  79      * discovered field to determine whether a normal Reference object needs
  80      * special treatment.  If the referent is non-null and not known to be
  81      * live, then it may need to be discovered for possible later
  82      * notification.  But if the discovered field is non-null, then either (1)
  83      * it has already been discovered, or (2) it is in the pending list.

  84      *
  85      * FinalReference differs from other references, because a FinalReference
  86      * is not cleared when notified.  The referent being null or not cannot be
  87      * used to distinguish between the active state and pending or inactive
  88      * states.  However, FinalReferences do not support enqueue().  Instead,
  89      * the next field of a FinalReference object is set to the object when it
  90      * is added to the pending list, and the use of this as the value of next
  91      * in the enqueued and dequeued states maintains the non-active state.  An
  92      * additional check that the next field is null is required to determine
  93      * that a FinalReference object is active.

  94      *
  95      * Initial states:
  96      *   active/registered
  97      *   active/unregistered [1]
  98      *
  99      * Transitions:
 100      *   active/registered    -> pending/registered    - GC
 101      *                        -> inactive/registered   - clear
 102      *                        -> inactive/enqueued     - enqueue [2]
 103      *   pending/registered   -> pending/enqueued      - enqueue [2]
 104      *                        -> inactive/enqueued     - pending list processing
 105      *   pending/enqueued     -> inactive/enqueued     - pending list processing
 106      *                        -> pending/dequeued      - poll/remove
 107      *   pending/dequeued     -> inactive/dequeued     - pending list processing
 108      *   inactive/registered  -> inactive/enqueued     - enqueue [2]
 109      *   inactive/enqueued    -> inactive/dequeued     - poll/remove
 110      *
 111      *   active/unregistered  -> pending/unregistered  - GC
 112      *                        -> inactive/unregistered - GC, clear, enqueue
 113      *   pending/unregistered -> inactive/unregistered - pending list processing




  59      * referent = null; discovered = next element in pending-Reference list.
  60      *
  61      * Inactive: Neither Active nor Pending.
  62      * referent = null.
  63      *
  64      * Registered: Associated with a queue when created, and not yet added to
  65      * the queue.
  66      * queue = the associated queue.
  67      *
  68      * Enqueued: Added to the associated queue, and not yet removed.
  69      * queue = ReferenceQueue.ENQUEUE; next = next entry in list, or this to
  70      * indicate end of list.
  71      *
  72      * Dequeued: Added to the associated queue and then removed.
  73      * queue = ReferenceQueue.NULL; next = this.
  74      *
  75      * Unregistered: Not associated with a queue when created.
  76      * queue = ReferenceQueue.NULL.
  77      *
  78      * The collector only needs to examine the referent field and the
  79      * discovered field to determine whether a normal (non-FinalReference)
  80      * Reference object needs special treatment.  If the referent is non-null
  81      * and not known to be live, then it may need to be discovered for
  82      * possible later notification.  But if the discovered field is non-null,
  83      * then either (1) it has already been discovered, or (2) it is in the
  84      * pending list.
  85      *
  86      * FinalReference (which exists to support finalization, which was
  87      * deprecated in JDK 9) differs from normal references, because a
  88      * FinalReference is not cleared when notified.  The referent being null
  89      * or not cannot be used to distinguish between the active state and
  90      * pending or inactive states.  However, FinalReferences do not support
  91      * enqueue().  Instead, the next field of a FinalReference object is set
  92      * to "this" when it is added to the pending list.  The use of "this"
  93      * as the value of next in the enqueued and dequeued states maintains the
  94      * non-active state.  An additional check that the next field is null is
  95      * required to determine that a FinalReference object is active.
  96      *
  97      * Initial states:
  98      *   active/registered
  99      *   active/unregistered [1]
 100      *
 101      * Transitions:
 102      *   active/registered    -> pending/registered    - GC
 103      *                        -> inactive/registered   - clear
 104      *                        -> inactive/enqueued     - enqueue [2]
 105      *   pending/registered   -> pending/enqueued      - enqueue [2]
 106      *                        -> inactive/enqueued     - pending list processing
 107      *   pending/enqueued     -> inactive/enqueued     - pending list processing
 108      *                        -> pending/dequeued      - poll/remove
 109      *   pending/dequeued     -> inactive/dequeued     - pending list processing
 110      *   inactive/registered  -> inactive/enqueued     - enqueue [2]
 111      *   inactive/enqueued    -> inactive/dequeued     - poll/remove
 112      *
 113      *   active/unregistered  -> pending/unregistered  - GC
 114      *                        -> inactive/unregistered - GC, clear, enqueue
 115      *   pending/unregistered -> inactive/unregistered - pending list processing


< prev index next >