Update CodecDataObjectGenerator documentation
[mdsal.git] / binding / mdsal-binding-dom-codec / src / main / java / org / opendaylight / mdsal / binding / dom / codec / impl / CodecDataObjectGenerator.java
index fd62b1be79cae77504e8bef3cfcd2889e1da4bb7..d8f1f367249269a5bed7e3ae5d12132de1eb2ac4 100644 (file)
@@ -16,9 +16,11 @@ import static org.opendaylight.mdsal.binding.dom.codec.impl.ByteBuddyUtils.invok
 import static org.opendaylight.mdsal.binding.dom.codec.impl.ByteBuddyUtils.putField;
 
 import com.google.common.base.MoreObjects.ToStringHelper;
-import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Maps;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodHandles.Lookup;
+import java.lang.invoke.VarHandle;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -28,7 +30,6 @@ import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Objects;
 import java.util.Optional;
-import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
 import net.bytebuddy.ByteBuddy;
 import net.bytebuddy.description.field.FieldDescription;
 import net.bytebuddy.description.method.MethodDescription;
@@ -52,9 +53,7 @@ import net.bytebuddy.implementation.bytecode.member.MethodVariableAccess;
 import net.bytebuddy.jar.asm.Label;
 import net.bytebuddy.jar.asm.MethodVisitor;
 import net.bytebuddy.jar.asm.Opcodes;
-import org.eclipse.jdt.annotation.NonNull;
 import org.eclipse.jdt.annotation.Nullable;
-import org.opendaylight.mdsal.binding.dom.codec.impl.ClassGeneratorBridge.BridgeProvider;
 import org.opendaylight.mdsal.binding.dom.codec.impl.ClassGeneratorBridge.LocalNameProvider;
 import org.opendaylight.mdsal.binding.dom.codec.impl.ClassGeneratorBridge.NodeContextSupplierProvider;
 import org.opendaylight.mdsal.binding.dom.codec.loader.CodecClassLoader;
@@ -69,9 +68,11 @@ import org.slf4j.LoggerFactory;
  *
  * <p>
  * Code generation here is probably more involved than usual mainly due to the fact we *really* want to express the
- * strong connection between a generated class and BindingCodecContext in terms of a true constant, which boils down to
- * {@code private static final NodeContextSupplier NCS}. Having such constants provides significant boost to JITs
- * ability to optimize code -- especially with inlining and constant propagation.
+ * strong connection between a generated class to the extent possible. In most cases (grouping-generated types) this
+ * involves one level of indirection, which is a safe approach. If we are dealing with a type generated outside of a
+ * grouping statement, though, we are guaranteed instantiation-invariance and hence can hard-wire to a runtime-constant
+ * {@link NodeContextSupplier} -- which  provides significant boost to JITs ability to optimize code -- especially with
+ * inlining and constant propagation.
  *
  * <p>
  * The accessor mapping performance is critical due to users typically not taking care of storing the results acquired
@@ -90,7 +91,7 @@ import org.slf4j.LoggerFactory;
  * we end up generating a class with the following layout:
  * <pre>
  *     public final class Foo$$$codecImpl extends CodecDataObject implements Foo {
- *         private static final AtomicRefereceFieldUpdater&lt;Foo$$$codecImpl, Object&gt; getBar$$$A;
+ *         private static final VarHandle getBar$$$V;
  *         private volatile Object getBar;
  *
  *         public Foo$$$codecImpl(NormalizedNodeContainer data) {
@@ -98,7 +99,7 @@ import org.slf4j.LoggerFactory;
  *         }
  *
  *         public Bar getBar() {
- *             return (Bar) codecMember(getBar$$$A, "bar");
+ *             return (Bar) codecMember(getBar$$$V, "bar");
  *         }
  *     }
  * </pre>
@@ -108,11 +109,13 @@ import org.slf4j.LoggerFactory;
  * single place in a maintainable form. The glue code is extremely light (~6 instructions), which is beneficial on both
  * sides of invocation:
  * - generated method can readily be inlined into the caller
- * - it forms a call site into which codeMember() can be inlined with AtomicReferenceFieldUpdater being constant
+ * - it forms a call site into which codeMember() can be inlined with VarHandle being constant
  *
  * <p>
- * The second point is important here, as it allows the invocation logic around AtomicRefereceFieldUpdater to completely
- * disappear, becoming synonymous with operations of a volatile field.
+ * The second point is important here, as it allows the invocation logic around VarHandle to completely disappear,
+ * becoming synonymous with operations on a field. Even though the field itself is declared as volatile, it is only ever
+ * accessed through helper method using VarHandles -- and those helpers are using relaxed field ordering
+ * of {@code getAcquire()}/{@code setRelease()} memory semantics.
  *
  * <p>
  * Furthermore there are distinct {@code codecMember} methods, each of which supports a different invocation style:
@@ -157,10 +160,12 @@ import org.slf4j.LoggerFactory;
  * This strategy works due to close cooperation with the target ClassLoader, as the entire code generation and loading
  * block runs with the class loading lock for this FQCN and the reference is not leaked until the process completes.
  */
-abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements ClassGenerator<T>, BridgeProvider {
-    // Not reusable defintion: we can inline NodeContextSuppliers without a problem
+abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements ClassGenerator<T> {
+    // Not reusable definition: we can inline NodeContextSuppliers without a problem
+    // FIXME: 6.0.0: wire this implementation, which requires that BindingRuntimeTypes provides information about types
+    //               being genenerated from within a grouping
     private static final class Fixed<T extends CodecDataObject<?>> extends CodecDataObjectGenerator<T>
-            implements NodeContextSupplierProvider {
+            implements NodeContextSupplierProvider<T> {
         private final ImmutableMap<Method, NodeContextSupplier> properties;
 
         Fixed(final Builder<?> template, final ImmutableMap<Method, NodeContextSupplier> properties,
@@ -198,7 +203,7 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
 
     // Reusable definition: we have to rely on context lookups
     private static final class Reusable<T extends CodecDataObject<?>> extends CodecDataObjectGenerator<T>
-            implements LocalNameProvider {
+            implements LocalNameProvider<T> {
         private final ImmutableMap<Method, ValueNodeCodecContext> simpleProperties;
         private final Map<Method, Class<?>> daoProperties;
 
@@ -279,7 +284,7 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
     private final Builder<?> template;
     private final Method keyMethod;
 
-    private CodecDataObjectGenerator(final Builder<?> template, final @Nullable Method keyMethod) {
+    CodecDataObjectGenerator(final Builder<?> template, final @Nullable Method keyMethod) {
         this.template = requireNonNull(template);
         this.keyMethod = keyMethod;
     }
@@ -341,32 +346,6 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
                 .make());
     }
 
-    @Override
-    public Class<T> customizeLoading(final @NonNull Supplier<Class<T>> loader) {
-        final BridgeProvider prev = ClassGeneratorBridge.setup(this);
-        try {
-            final Class<T> result = loader.get();
-
-            /*
-             * This a bit of magic to support NodeContextSupplier constants. These constants need to be resolved
-             * while we have the information needed to find them -- that information is being held in this instance
-             * and we leak it to a thread-local variable held by CodecDataObjectBridge.
-             *
-             * By default the JVM will defer class initialization to first use, which unfortunately is too late for
-             * us, and hence we need to force class to initialize.
-             */
-            try {
-                Class.forName(result.getName(), true, result.getClassLoader());
-            } catch (ClassNotFoundException e) {
-                throw new LinkageError("Failed to find newly-defined " + result, e);
-            }
-
-            return result;
-        } finally {
-            ClassGeneratorBridge.tearDown(prev);
-        }
-    }
-
     abstract Builder<T> generateGetters(Builder<T> builder);
 
     abstract ArrayList<Method> getterMethods();
@@ -419,11 +398,12 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
     }
 
     private abstract static class AbstractMethodImplementation implements Implementation {
-        private static final Generic BB_ARFU = TypeDefinition.Sort.describe(AtomicReferenceFieldUpdater.class);
+        private static final Generic BB_HANDLE = TypeDefinition.Sort.describe(VarHandle.class);
         private static final Generic BB_OBJECT = TypeDefinition.Sort.describe(Object.class);
         private static final StackManipulation OBJECT_CLASS = ClassConstant.of(TypeDescription.OBJECT);
-        private static final StackManipulation ARFU_NEWUPDATER = invokeMethod(AtomicReferenceFieldUpdater.class,
-            "newUpdater", Class.class, Class.class, String.class);
+        private static final StackManipulation LOOKUP = invokeMethod(MethodHandles.class, "lookup");
+        private static final StackManipulation FIND_VAR_HANDLE = invokeMethod(Lookup.class,
+            "findVarHandle", Class.class, String.class, Class.class);
 
         static final int PRIV_CONST = Opcodes.ACC_PRIVATE | Opcodes.ACC_STATIC | Opcodes.ACC_FINAL
                 | Opcodes.ACC_SYNTHETIC;
@@ -432,36 +412,38 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
         final TypeDescription retType;
         // getFoo
         final String methodName;
-        // getFoo$$$A
-        final String arfuName;
+        // getFoo$$$V
+        final String handleName;
 
         AbstractMethodImplementation(final String methodName, final TypeDescription retType) {
             this.methodName = requireNonNull(methodName);
             this.retType = requireNonNull(retType);
-            this.arfuName = methodName + "$$$A";
+            this.handleName = methodName + "$$$V";
         }
 
         @Override
         public InstrumentedType prepare(final InstrumentedType instrumentedType) {
             final InstrumentedType tmp = instrumentedType
-                    // private static final AtomicReferenceFieldUpdater<This, Object> getFoo$$$A;
-                    .withField(new FieldDescription.Token(arfuName, PRIV_CONST, BB_ARFU))
+                    // private static final VarHandle getFoo$$$V;
+                    .withField(new FieldDescription.Token(handleName, PRIV_CONST, BB_HANDLE))
                     // private volatile Object getFoo;
                     .withField(new FieldDescription.Token(methodName, PRIV_VOLATILE, BB_OBJECT));
 
             return tmp.withInitializer(new ByteCodeAppender.Simple(
-                // getFoo$$$A = AtomicReferenceFieldUpdater.newUpdater(This.class, Object.class, "getFoo");
+                // TODO: acquiring lookup is expensive, we should share it across all initialization
+                // getFoo$$$V = MethodHandles.lookup().findVarHandle(This.class, "getFoo", Object.class);
+                LOOKUP,
                 ClassConstant.of(tmp),
-                OBJECT_CLASS,
                 new TextConstant(methodName),
-                ARFU_NEWUPDATER,
-                putField(tmp, arfuName)));
+                OBJECT_CLASS,
+                FIND_VAR_HANDLE,
+                putField(tmp, handleName)));
         }
     }
 
     private static final class KeyMethodImplementation extends AbstractMethodImplementation {
         private static final StackManipulation CODEC_KEY = invokeMethod(CodecDataObject.class,
-            "codecKey", AtomicReferenceFieldUpdater.class);
+            "codecKey", VarHandle.class);
 
         KeyMethodImplementation(final String methodName, final TypeDescription retType) {
             super(methodName, retType);
@@ -471,9 +453,9 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
         public ByteCodeAppender appender(final Target implementationTarget) {
             final TypeDescription instrumentedType = implementationTarget.getInstrumentedType();
             return new ByteCodeAppender.Simple(
-                // return (FooType) codecKey(getFoo$$$A);
+                // return (FooType) codecKey(getFoo$$$V);
                 THIS,
-                getField(instrumentedType, arfuName),
+                getField(instrumentedType, handleName),
                 CODEC_KEY,
                 TypeCasting.to(retType),
                 MethodReturn.REFERENCE);
@@ -489,7 +471,7 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
      */
     private static final class SimpleGetterMethodImplementation extends AbstractMethodImplementation {
         private static final StackManipulation CODEC_MEMBER = invokeMethod(CodecDataObject.class,
-            "codecMember", AtomicReferenceFieldUpdater.class, String.class);
+            "codecMember", VarHandle.class, String.class);
         private static final StackManipulation BRIDGE_RESOLVE = invokeMethod(ClassGeneratorBridge.class,
             "resolveLocalName", String.class);
         private static final Generic BB_STRING = TypeDefinition.Sort.describe(String.class);
@@ -519,9 +501,9 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
         public ByteCodeAppender appender(final Target implementationTarget) {
             final TypeDescription instrumentedType = implementationTarget.getInstrumentedType();
             return new ByteCodeAppender.Simple(
-                // return (FooType) codecMember(getFoo$$$A, getFoo$$$S);
+                // return (FooType) codecMember(getFoo$$$V, getFoo$$$S);
                 THIS,
-                getField(instrumentedType, arfuName),
+                getField(instrumentedType, handleName),
                 getField(instrumentedType, stringName),
                 CODEC_MEMBER,
                 TypeCasting.to(retType),
@@ -531,7 +513,7 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
 
     private static final class StructuredGetterMethodImplementation extends AbstractMethodImplementation {
         private static final StackManipulation CODEC_MEMBER = invokeMethod(CodecDataObject.class,
-            "codecMember", AtomicReferenceFieldUpdater.class, Class.class);
+            "codecMember", VarHandle.class, Class.class);
 
         private final Class<?> bindingClass;
 
@@ -545,9 +527,9 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
         public ByteCodeAppender appender(final Target implementationTarget) {
             final TypeDescription instrumentedType = implementationTarget.getInstrumentedType();
             return new ByteCodeAppender.Simple(
-                // return (FooType) codecMember(getFoo$$$A, FooType.class);
+                // return (FooType) codecMember(getFoo$$$V, FooType.class);
                 THIS,
-                getField(instrumentedType, arfuName),
+                getField(instrumentedType, handleName),
                 ClassConstant.of(TypeDefinition.Sort.describe(bindingClass).asErasure()),
                 CODEC_MEMBER,
                 TypeCasting.to(retType),
@@ -557,7 +539,7 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
 
     private static final class SupplierGetterMethodImplementation extends AbstractMethodImplementation {
         private static final StackManipulation CODEC_MEMBER = invokeMethod(CodecDataObject.class,
-            "codecMember", AtomicReferenceFieldUpdater.class, NodeContextSupplier.class);
+            "codecMember", VarHandle.class, NodeContextSupplier.class);
         private static final StackManipulation BRIDGE_RESOLVE = invokeMethod(ClassGeneratorBridge.class,
             "resolveNodeContextSupplier", String.class);
         private static final Generic BB_NCS = TypeDefinition.Sort.describe(NodeContextSupplier.class);
@@ -587,9 +569,9 @@ abstract class CodecDataObjectGenerator<T extends CodecDataObject<?>> implements
         public ByteCodeAppender appender(final Target implementationTarget) {
             final TypeDescription instrumentedType = implementationTarget.getInstrumentedType();
             return new ByteCodeAppender.Simple(
-                // return (FooType) codecMember(getFoo$$$A, getFoo$$$C);
+                // return (FooType) codecMember(getFoo$$$V, getFoo$$$C);
                 THIS,
-                getField(instrumentedType, arfuName),
+                getField(instrumentedType, handleName),
                 getField(instrumentedType, contextName),
                 CODEC_MEMBER,
                 TypeCasting.to(retType),