--- /dev/null 2016-01-24 08:40:46.523299426 +0100 +++ new/src/java.base/share/classes/java/lang/ref/Ephemeron.java 2016-01-24 11:21:30.332171337 +0100 @@ -0,0 +1,162 @@ +/* + * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.lang.ref; + + +/** + * {@code Ephemeron} objects are a special kind of {@code WeakReference} + * objects, which hold two referents (a normal referent, also called a key referent, + * and a value referent) and do not prevent their referents from being made + * finalizable, finalized, and then reclaimed. In addition to the key referent, + * which adheres to the referent behavior of a {@code WeakReference}, + * an ephemeron also holds a value referent whose reachabiliy strength is affected + * by the reachability strength of the key referent. The value referent of an + * Ephemeron instance is considered: + *
    + *
  • strongly reachable if the key referent of the same Ephemeron + * object is strongly reachable, or if the value referent is otherwise strongly + * reachable. + *
    • + *
  • softly reachable if it is not strongly reachable, and the key referent of + * the same Ephemeron object is softly reachable, or if the value referent is + * otherwise softly reachable. + *
    • + *
  • weakly reachable if it is neither strongly nor softly reachable, and the + * key referent of the same Ephemeron object is weakly reachable, or if the value + * referent is otherwise weakly reachable. + *
    • + *
+ *

When the collector clears an Ephemeron object instance (according to the rules + * expressed for clearing WeakReference object instances), the Ephemeron instance's + * key referent and value referent are simultaneously and atomically cleared. + *

By convenience, the Ephemeron's normal referent is also called the key referent, + * and can be obtained either by invoking {@link #get} or {@link #getKey} while + * the value referent can be obtained by invoking {@link #getValue} method. + *

Reachability (should be moved to package-level docs)

+ * Going from strongest to weakest, the different levels of + * reachability reflect the life cycle of an object. They are + * operationally defined as follows: + *
    + *
  • An object is strongly reachable if it can be reached by some thread + * without traversing any reference objects, or by traversing the value of an Ephemeron + * whose key is strongly reachable. A newly-created object is strongly reachable by + * the thread that created it + *
    • + *
  • An object is softly reachable if it is not strongly reachable but + * can be reached by traversing a soft reference or by traversing the value of an + * Ephemeron whose key is softly reachable. + *
    • + *
  • An object is weakly reachable if it is neither strongly nor softly + * reachable but can be reached by traversing a weak reference or by traversing the + * value of an ephemeron whose key is weakly reachable. When the weak references + * to a weakly-reachable object are cleared, the object becomes eligible for + * finalization. + *
    • + *
  • An object is phantom reachable if it is neither + * strongly, softly, nor weakly reachable, it has been finalized, and + * some phantom reference refers to it. + *
    • + *
  • Finally, an object is unreachable, and therefore + * eligible for reclamation, when it is not reachable in any of the + * above ways. + *
    • + *
+ * + * @since 9 + */ + +public class Ephemeron extends WeakReference { + + /** + * The value field is treated specially by GC + */ + private V value; + + /** + * Creates a new ephemeron that refers to the given key and + * given value. The new ephemeron is not registered with any queue. + * + * @param key the key (or referent) the new ephemeron will refer to + * @param value the value the new ephemeron will hold until cleared + */ + public Ephemeron(K key, V value) { + super(key); + this.value = value; + } + + /** + * Creates a new ephemeron that refers to the given key and + * given value and is registered with the given queue. + * + * @param key the key (or referent) the new ephemeron will refer to + * @param value the value the new ephemeron will hold until cleared + * @param q the queue with which the ephemeron is to be registered, + * or {@code null} if registration is not required + */ + public Ephemeron(K key, V value, ReferenceQueue q) { + super(key, q); + this.value = value; + } + + /** + * Returns this ephemeron object's referent, also known as the key. + * If this ephemeron object has been cleared, either by the program or by + * the garbage collector, then this method returns null. + * + * @return The key object to which this ephemeron object refers, or + * null if this ephemeron object has been cleared + * @see #getValue() + */ + public K getKey() { + return get(); + } + + /** + * Returns this ephemeron object's value. + * If this ephemeron object has been cleared, either by the program or by + * the garbage collector, then this method returns null. + * + * @return The value object to which this ephemeron object refers, or + * null if this ephemeron object has been cleared + * @see #getKey() + */ + public V getValue() { + return value; + } + + /** + * Clears this ephemeron object, resetting both the key and + * the value to null. Invoking this method will not cause this + * ephemeron object to be enqueued. + *

This method is invoked only by Java code; when the garbage collector + * clears ephemerons it does so directly, without invoking this method. + */ + @Override + public void clear() { + super.clear(); + this.value = null; + } +} --- /dev/null 2016-01-24 08:40:46.523299426 +0100 +++ new/test/java/lang/ref/EphemeronTests.java 2016-01-24 11:21:30.578167102 +0100 @@ -0,0 +1,215 @@ +/* + * Copyright (c) 1997, 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/* @test + * @run main/othervm -Xmx16m EphemeronTests + * @summary Basic functional tests for Ephemerons + * @author Peter Levart + */ + +import java.lang.ref.Ephemeron; +import java.lang.ref.Reference; +import java.lang.ref.SoftReference; +import java.lang.ref.WeakReference; +import java.util.ArrayList; +import java.util.List; +import java.util.function.Function; + +public class EphemeronTests { + + public static void main(String[] args) throws Exception { + + testValueToKeyChain(100, true); + testValueToKeyChain(100, false); + + testReachability(SoftReference::new); + testReachability(WeakReference::new); + } + + static class Key { + final int i; + + Key(int i) { + this.i = i; + } + + @Override + public String toString() { + return "k" + i; + } + } + + static class Value { + final Key key; + + Value(Key key) { + this.key = key; + } + + @Override + public String toString() { + return "v(" + key + ")"; + } + } + + static class Eph extends Ephemeron { + public Eph(Key key, Value value) { + super(key, value); + } + + @Override + public String toString() { + return getKey() + "=" + getValue(); + } + } + + static void testValueToKeyChain(int size, boolean forwardChaining) throws Exception { + System.out.println(); + System.out.println((forwardChaining ? "Forward" : "Backward") + + " chaining of value->key ..."); + System.out.println(); + List ephs = new ArrayList<>(size); + + Key k1 = new Key(1); + { + Key kp = k1; + for (int i = 2; i <= size; i++) { + Key ki = new Key(i); + ephs.add( + forwardChaining + ? new Eph(kp, new Value(ki)) + : new Eph(ki, new Value(kp)) + ); + kp = ki; + } + ephs.add( + forwardChaining + ? new Eph(kp, new Value(k1)) + : new Eph(k1, new Value(kp)) + ); + kp = null; + } + + fillHeap(); + System.out.println("1: " + toString(ephs)); + for (Eph eph : ephs) assertAlive(eph); + k1.getClass(); // reachabilityFence + + k1 = null; + fillHeap(); + System.out.println("2: " + toString(ephs)); + for (Eph eph : ephs) assertCleared(eph); + } + + static void testReachability(Function> referenceConstructor) { + Reference kRef, vRef; + Ephemeron eph; + Object k; + { + k = new Object(); + Object v = new Object(); + kRef = referenceConstructor.apply(k); + vRef = referenceConstructor.apply(v); + eph = new Ephemeron<>(k, v); + v = null; + } + + System.out.println(); + System.out.println(kRef.getClass().getSimpleName() + " reachability test"); + System.out.println(); + + while (true) { + fillHeap(); + if ((k = kRef.get()) == null) { + System.out.println("key cleared"); + assertCleared(kRef); + assertCleared(eph); + assertCleared(vRef); + break; + } else { + System.out.println("key alive"); + assertAlive(kRef); + assertAlive(eph); + assertAlive(vRef); + k.getClass(); // reachabilityFence + } + k = null; + } + } + + // utils + + static void fillHeap() { + long t0 = System.nanoTime(); + Object junk = null; + try { + while (true) { + Object[] nj = new Object[16384]; + nj[0] = junk; + junk = nj; + nj = null; + } + } catch (OutOfMemoryError e) { + junk = null; + System.gc(); + } + long t = System.nanoTime() - t0; + System.out.println("Fill Heap (" + (t / 1000000L) + " ms)"); + try { + Thread.sleep(100L); + } catch (InterruptedException e) {} + } + + static void assertAlive(Reference reference) { + if (reference.get() == null) { + throw new AssertionError(reference + " is cleared"); + } + } + + static void assertAlive(Ephemeron ephemeron) { + if (ephemeron.getKey() == null || ephemeron.getValue() == null) { + throw new AssertionError(ephemeron + " is cleared"); + } + } + + static void assertCleared(Reference reference) { + if (reference.get() != null) { + throw new AssertionError(reference + " is not cleared"); + } + } + + static void assertCleared(Ephemeron ephemeron) { + if (ephemeron.getKey() != null || ephemeron.getValue() != null) { + throw new AssertionError(ephemeron + " is not cleared"); + } + } + + static String toString(List list) { + if (list == null) return "null"; + if (list.size() <= 10) return list.toString(); + String prefix = list.subList(0, 5).toString(); + String suffix = list.subList(list.size() - 5, list.size()).toString(); + + return prefix.substring(0, prefix.length() - 1) + ", ..., " + suffix.substring(1); + } +}