解读 Reference

    /* A Reference instance is in one of four possible internal states:
     *
     *     Active: Subject to special treatment by the garbage collector.  Some
     *     time after the collector detects that the reachability of the
     *     referent has changed to the appropriate state, it changes the
     *     instance's state to either Pending or Inactive, depending upon
     *     whether or not the instance was registered with a queue when it was
     *     created.  In the former case it also adds the instance to the
     *     pending-Reference list.  Newly-created instances are Active.
     *
     *     Pending: An element of the pending-Reference list, waiting to be
     *     enqueued by the Reference-handler thread.  Unregistered instances
     *     are never in this state.
     *
     *     Enqueued: An element of the queue with which the instance was
     *     registered when it was created.  When an instance is removed from
     *     its ReferenceQueue, it is made Inactive.  Unregistered instances are
     *     never in this state.
     *
     *     Inactive: Nothing more to do.  Once an instance becomes Inactive its
     *     state will never change again.
     *
     * The state is encoded in the queue and next fields as follows:
     *
     *     Active: queue = ReferenceQueue with which instance is registered, or
     *     ReferenceQueue.NULL if it was not registered with a queue; next =
     *     null.
     *
     *     Pending: queue = ReferenceQueue with which instance is registered;
     *     next = this
     *
     *     Enqueued: queue = ReferenceQueue.ENQUEUED; next = Following instance
     *     in queue, or this if at end of list.
     *
     *     Inactive: queue = ReferenceQueue.NULL; next = this.
     *
     * With this scheme the collector need only examine the next field in order
     * to determine whether a Reference instance requires special treatment: If
     * the next field is null then the instance is active; if it is non-null,
     * then the collector should treat the instance normally.
     *
     * To ensure that a concurrent collector can discover active Reference
     * objects without interfering with application threads that may apply
     * the enqueue() method to those objects, collectors should link
     * discovered objects through the discovered field. The discovered
     * field is also used for linking Reference objects in the pending list.
     *
     * 一个 Reference 实例处于如下四种可能的状态之一：
     *
     *    Active: 被垃圾回收器特殊对待的状态。当垃圾回收器检测到 referent 不是强可达时，就会将 Reference 实
     *    例的状态调整为 Pending 或 Inactive，具体调整为哪一种取决于创建 Reference 实例时是否注册了 queue。
     *    如果注册了就进入 Pending 状态，也就是把 Reference 实例添加到 pending-Reference 链表中。新建的
     *    Reference 实例处于 Active 状态。
     *    
     *    Pending: 处于 pending-Reference 链表中，等待 Reference-handler 线程将它们放入到 queue 中。未
     *    注册的实例永远也不会进入此状态。
     *    
     *    Enqueued: 处于 queue 中，即创建 Reference 实例时所注册的 ReferenceQueue，当 Reference 实例被
     *    ReferenceQueue 移除时，会进入Inactive 状态。未注册的实例永远也不会进入此状态。
     *    
     *    Inactive: 在此状态下不需要再做什么。一旦一个实例进入 Inactive 状态，其状态就不会再发生改变。
     *    
     * Reference 实例的状态被编码在 queue 和 next 字段中：
     *    
     *    Active: queue 等于注册的 ReferenceQueue，若没注册就等于 ReferenceQueue.NULL。next 等于 null；
     *    
     *    Pending: queue 等于参与注册的 ReferenceQueue；next 等于 this；
     *    
     *    Enqueued: queue 等于 ReferenceQueue.ENQUEUED；next 等于 queue 中下一个实例，如果实例处于 queue
     *    的末尾，那么 next 等于 this。
     *    
     *    Inactive: queue 等于 ReferenceQueue.NULL; next 等于 this。
     *    
     * 有了上述方案，垃圾回收器只需要检查 next 字段就能决定是否要特殊对待一个 Reference 实例：如果 next 字段为
     * 空，那其状态就是 Active；如果不是空，那就不用特殊对待。
     * 
     *
     * 应用线程会调用了 Reference 对象的 enqueue() 方法（这个方法修改了由 next 字段组织成的 ReferenceQueue），
     * 为了保证并发的垃圾回收器不对应用线程产生干扰，垃圾回收线程在将 Active 状态的 Reference 对象迁移到 Pending
     * 状态时，要使用 discovered 字段。discovered 字段就是用于组织 pending-Reference 链表的。
     */
    private T referent;         /* Treated specially by GC */
    volatile ReferenceQueue<? super T> queue;
    /* When active:   NULL
     *     pending:   this
     *    Enqueued:   next reference in queue (or this if last)
     *    Inactive:   this
     */
    @SuppressWarnings("rawtypes")
    volatile Reference next;
    /* When active:   next element in a discovered reference list maintained by GC (or this if last)
     *     pending:   next element in the pending list (or null if last)
     *   otherwise:   NULL
     */
    transient private Reference<T> discovered;  /* used by VM */
    /* Object used to synchronize with the garbage collector.  The collector
     * must acquire this lock at the beginning of each collection cycle.  It is
     * therefore critical that any code holding this lock complete as quickly
     * as possible, allocate no new objects, and avoid calling user code.
     */
    static private class Lock { }
    private static Lock lock = new Lock();
    /* List of References waiting to be enqueued.  The collector adds
     * References to this list, while the Reference-handler thread removes
     * them.  This list is protected by the above lock object. The
     * list uses the discovered field to link its elements.
     */
    private static Reference<Object> pending = null;

    static boolean tryHandlePending(boolean waitForNotify) {
        Reference<Object> r;
        Cleaner c;
        try {
            synchronized (lock) {
                if (pending != null) {
                    r = pending;
                    // 'instanceof' might throw OutOfMemoryError sometimes
                    // so do this before un-linking 'r' from the 'pending' chain...
                    c = r instanceof Cleaner ? (Cleaner) r : null;
                    // unlink 'r' from 'pending' chain
                    pending = r.discovered;
                    r.discovered = null;
                } else {
                    // The waiting on the lock may cause an OutOfMemoryError
                    // because it may try to allocate exception objects.
                    if (waitForNotify) {
                        lock.wait();
                    }
                    // retry if waited
                    return waitForNotify;
                }
            }
        } catch (OutOfMemoryError x) {
            // Give other threads CPU time so they hopefully drop some live references
            // and GC reclaims some space.
            // Also prevent CPU intensive spinning in case 'r instanceof Cleaner' above
            // persistently throws OOME for some time...
            Thread.yield();
            // retry
            return true;
        } catch (InterruptedException x) {
            // retry
            return true;
        }
        // Fast path for cleaners
        if (c != null) {
            c.clean();
            return true;
        }
        ReferenceQueue<? super Object> q = r.queue;
        if (q != ReferenceQueue.NULL) q.enqueue(r);
        return true;
    }

final class Finalizer extends FinalReference {
    /* A native method that invokes an arbitrary object's finalize method is
       required since the finalize method is protected
     */
    static native void invokeFinalizeMethod(Object o) throws Throwable;
    private static ReferenceQueue queue = new ReferenceQueue();
    private static Finalizer unfinalized = null;
    private static final Object lock = new Object();
    private Finalizer
        next = null,
        prev = null;
    private Finalizer(Object finalizee) {
        super(finalizee, queue);
        add();
    }
    /* Invoked by VM */
    static void register(Object finalizee) {
        new Finalizer(finalizee);
    }  
    private void add() {
        synchronized (lock) {
            if (unfinalized != null) {
                this.next = unfinalized;
                unfinalized.prev = this;
            }
            unfinalized = this;
        }
    }
    ...
}

public class WeakHashMap<K,V> extends AbstractMap<K,V> implements Map<K,V> {
    ...
    /**
     * The table, resized as necessary. Length MUST Always be a power of two.
     */
    Entry<K,V>[] table;
    /**
     * The number of key-value mappings contained in this weak hash map.
     */
    private int size;
    
    ...
    /**
     * Reference queue for cleared WeakEntries
     */
    private final ReferenceQueue<Object> queue = new ReferenceQueue<>();
    
    ...
    /**
     * Expunges stale entries from the table.
     */
    private void expungeStaleEntries() {
        for (Object x; (x = queue.poll()) != null; ) {  // 从 queue 中取出要被 GC 的 entry，通过下面的代码，将其从 table 中清理掉
            synchronized (queue) {
                @SuppressWarnings("unchecked")
                Entry<K,V> e = (Entry<K,V>) x;
                int i = indexFor(e.hash, table.length);
                Entry<K,V> prev = table[i];
                Entry<K,V> p = prev;
                while (p != null) {
                    Entry<K,V> next = p.next;
                    if (p == e) {
                        if (prev == e)
                            table[i] = next;   // entry 在 table[i] 链表的头部，直接将头部设置为 entry 的下一个元素
                        else
                            prev.next = next;  // entry 在 table[i] 链表的中间，将 entry 的前一个元素的 next 指向 entry 的下一个元素
                        // Must not null out e.next;
                        // stale entries may be in use by a HashIterator
                        e.value = null; // Help GC
                        size--;
                        break;
                    }
                    prev = p;
                    p = next;
                }
            }
        }
    }
    
    ...
    /**
     * Removes all of the mappings from this map.
     * The map will be empty after this call returns.
     */
    public void clear() {
        // clear out ref queue. We don't need to expunge entries
        // since table is getting cleared.
        while (queue.poll() != null)
            ;
        modCount++;
        Arrays.fill(table, null);
        size = 0;
        // Allocation of array may have caused GC, which may have caused
        // additional entries to go stale.  Removing these entries from the
        // reference queue will make them eligible for reclamation.
        while (queue.poll() != null)
            ;
    }
    
    ...
    private static class Entry<K,V> extends WeakReference<Object> implements Map.Entry<K,V> {
        V value;
        final int hash;
        Entry<K,V> next;
        /**
         * Creates new entry.
         */
        Entry(Object key, V value, ReferenceQueue<Object> queue, int hash, Entry<K,V> next) {
            super(key, queue);  // 将 key 设置到 Reference 的 referent 字段；将 queue 设置到 Reference 的 queue 字段
            this.value = value;
            this.hash  = hash;
            this.next  = next;
        }
        @SuppressWarnings("unchecked")
        public K getKey() {
            return (K) WeakHashMap.unmaskNull(get()); // 从 referent 字段上读取 key
        }
        
        ...
    }
    
    ...

    ...
    /**
     * 返回当前线程的 thread-local 变量的副本。如果当前线程没有这个
     * 变量的值，就调用 initialValue 方法，用其返回值来初始化该变量。
     *
     * @return 当前线程的本 thread-local 变量的值
     */
    public T get() {
        Thread t = Thread.currentThread();
        ThreadLocalMap map = getMap(t);
        if (map != null) {
            ThreadLocalMap.Entry e = map.getEntry(this);
            if (e != null) {
                @SuppressWarnings("unchecked")
                T result = (T)e.value;
                return result;
            }
        }
        return setInitialValue();
    }
    /**
     * set() 方法的变体，用于设置初始值。如果用户重写了 set() 方法，
     * 那么，该方法的存在还能确保初始值的成功设置。
     *
     * @return 初始值
     */
    private T setInitialValue() {
        T value = initialValue();
        Thread t = Thread.currentThread();
        ThreadLocalMap map = getMap(t);
        if (map != null)
            map.set(this, value);
        else
            createMap(t, value);  // 读取数据触发 threadLocals 的初始化
        return value;
    }
    /**
     * 将本 thread-local 变量在当前线程中的副本设置为指定的值。大多数子类都不需
     * 要重写该方法，如果有重写的需求，一般也是重写 initialValue 方法来为不同的
     * thread-local 变量提供初始的值。
     *
     * @param value 要为当前线程存储到本 thread-local 变量中的副本的值。
     */
    public void set(T value) {
        Thread t = Thread.currentThread();
        ThreadLocalMap map = getMap(t);
        if (map != null)
            map.set(this, value);
        else
            createMap(t, value);  // 设置数据触发 threadLocals 的初始化
    }
    
    ...
    /**
     * 获取当前线程的 threadLocals 字段的值。
     *
     * @param  t 当前线程
     * @return the map
     */
    ThreadLocalMap getMap(Thread t) {
        return t.threadLocals;
    }
    /**
     * 为当前线程初始化其 threadLocals 字段。
     *
     * @param t 当前线程
     * @param firstValue 存储到 map 里的第一个值
     */
    void createMap(Thread t, T firstValue) {
        t.threadLocals = new ThreadLocalMap(this, firstValue);
    }
    ...

    /**
     * ThreadLocalMap 是一个自定义的哈希 map，只适用于维护线程本地变量。它的任何操作都没有暴露到
     * ThreadLocal 类之外。该类是包私有的，以允许 Thread 类声明一个 ThreadLocalMap 类型的字段。
     * 为了适应大的和长期存活的变量，其 Entry 使用了弱引用来指向其 key。但是，由于没有注册引用队列，
     * 所以不保证一定会清除已经过期的 Entry，只有在哈希表满了，需要扩容且 rehash 的时候，才能保证
     * 清除已过期的 Entry。
     */
    static class ThreadLocalMap {
        /**
         * 本哈希 map 的 Entry 继承自 WeakReference，使用了 Reference 的 referent 字段作为
         * key（它永远是一个 ThreadLocal 对象）。当 key 为 null（比如 entry.get() == null）
         * 时，意味着不再存储该 key 了，所以其 entry 也应该从 table 中清除了。下面的代码把这样的
         * entry 叫做 “stale entries”（不新鲜的 entry）。
         */
        static class Entry extends WeakReference<ThreadLocal<?>> {
            /** The value associated with this ThreadLocal. */
            Object value;
            Entry(ThreadLocal<?> k, Object v) {
                super(k);  // Entry 没有注册 queue
                value = v;
            }
        }
        ...
    }