changeset 1746:65ec780a0374

8161928: Dynalink documentation updates Reviewed-by: hannesw, sundar
author attila
date Mon, 25 Jul 2016 10:58:58 +0200
parents 8a875db19be8
children 9c51738fd0e3
files src/jdk.dynalink/share/classes/jdk/dynalink/linker/GuardingTypeConverterFactory.java src/jdk.dynalink/share/classes/jdk/dynalink/linker/package-info.java src/jdk.dynalink/share/classes/jdk/dynalink/linker/support/TypeUtilities.java src/jdk.dynalink/share/classes/jdk/dynalink/support/SimpleRelinkableCallSite.java
diffstat 4 files changed, 21 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.dynalink/share/classes/jdk/dynalink/linker/GuardingTypeConverterFactory.java	Thu Jul 21 17:13:46 2016 +0000
+++ b/src/jdk.dynalink/share/classes/jdk/dynalink/linker/GuardingTypeConverterFactory.java	Mon Jul 25 10:58:58 2016 +0200
@@ -108,15 +108,19 @@
      * language's objects to Java interfaces and classes by generating adapters
      * for them.
      * <p>
-     * The type of the invocation is {@code targetType(sourceType)}, while the
-     * type of the guard is {@code boolean(sourceType)}. You are allowed to
+     * The type of the invocation is <tt>(sourceType)&rarr;targetType</tt>, while the
+     * type of the guard is <tt>(sourceType)&rarr;boolean</tt>. You are allowed to
      * return unconditional invocations (with no guard) if the source type is
      * specific to your runtime and your runtime only.
-     * <p>Note that this method will never be invoked for type conversions
-     * allowed by the JLS 5.3 "Method Invocation Conversion", see
-     * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class)} for
-     * details. An implementation can assume it is never requested to produce a
-     * converter for these conversions.
+     * <p>Note that this method will never be invoked for
+     * {@link TypeUtilities#isMethodInvocationConvertible(Class, Class) method
+     * invocation conversions} as those can be automatically applied by
+     * {@link java.lang.invoke.MethodHandle#asType(MethodType)}.
+     * An implementation can assume it is never requested to produce a
+     * converter for those conversions. If a language runtime needs to customize
+     * method invocation conversions, it should
+     * {@link jdk.dynalink.DynamicLinkerFactory#setAutoConversionStrategy(MethodTypeConversionStrategy)
+     * set an autoconversion strategy in the dynamic linker factory} instead.
      * <p>Dynalink is at liberty to either cache some of the returned converters
      * or to repeatedly request the converter factory to create the same
      * conversion.
@@ -127,6 +131,9 @@
      * on whose behalf a type converter is requested. When a converter is
      * requested as part of linking an {@code invokedynamic} instruction the
      * supplier will return the lookup passed to the bootstrap method, otherwise
+     * if the method is invoked from within a
+     * {@link LinkerServices#getWithLookup(Supplier, jdk.dynalink.SecureLookupSupplier)}
+     * it will delegate to the secure lookup supplier. In any other case,
      * it will return the public lookup. A typical case where the lookup might
      * be needed is when the converter creates a Java adapter class on the fly
      * (e.g. to convert some object from the dynamic language into a Java
--- a/src/jdk.dynalink/share/classes/jdk/dynalink/linker/package-info.java	Thu Jul 21 17:13:46 2016 +0000
+++ b/src/jdk.dynalink/share/classes/jdk/dynalink/linker/package-info.java	Mon Jul 25 10:58:58 2016 +0200
@@ -96,10 +96,8 @@
  * language-specific manner if no other linker managed to handle the operation.)
  * </p><p>
  * A language runtime that wishes to make at least some of its linkers available
- * to other language runtimes for interoperability will need to declare the
- * class names of those linkers in
- * {@code /META-INF/services/jdk.dynalink.linker.GuardingDynamicLinker} file in
- * its distribution (typically, JAR file).
+ * to other language runtimes for interoperability will need to use a
+ * {@link jdk.dynalink.linker.GuardingDynamicLinkerExporter}.
  * </p><p>
  * Most language runtimes will be able to implement their own linking logic by
  * implementing {@link jdk.dynalink.linker.TypeBasedGuardingDynamicLinker}
--- a/src/jdk.dynalink/share/classes/jdk/dynalink/linker/support/TypeUtilities.java	Thu Jul 21 17:13:46 2016 +0000
+++ b/src/jdk.dynalink/share/classes/jdk/dynalink/linker/support/TypeUtilities.java	Mon Jul 25 10:58:58 2016 +0200
@@ -138,7 +138,7 @@
      * Determines whether one type can be converted to another type using a method invocation conversion, as per JLS 5.3
      * "Method Invocation Conversion". This is basically all conversions allowed by subtyping (see
      * {@link #isSubtype(Class, Class)}) as well as boxing conversion (JLS 5.1.7) optionally followed by widening
-     * reference conversion and unboxing conversion (JLS 5.1.8) optionally followed by widening primitive conversion.
+     * reference conversion, and unboxing conversion (JLS 5.1.8) optionally followed by widening primitive conversion.
      *
      * @param sourceType the type being converted from (call site type for parameter types, method type for return types)
      * @param targetType the parameter type being converted to (method type for parameter types, call site type for return types)
--- a/src/jdk.dynalink/share/classes/jdk/dynalink/support/SimpleRelinkableCallSite.java	Thu Jul 21 17:13:46 2016 +0000
+++ b/src/jdk.dynalink/share/classes/jdk/dynalink/support/SimpleRelinkableCallSite.java	Mon Jul 25 10:58:58 2016 +0200
@@ -90,9 +90,10 @@
 
 /**
  * A relinkable call site that implements monomorphic inline caching strategy,
- * only being linked to a single {@link GuardedInvocation}. If that invocation
- * is invalidated, it will throw it away and ask its associated
- * {@link DynamicLinker} to relink it.
+ * only being linked to a single {@link GuardedInvocation} at any given time.
+ * If the guard of that single invocation fails, or it has an invalidated
+ * switch point, or its invalidating exception triggered, then the call site
+ * will throw it away and ask its associated {@link DynamicLinker} to relink it.
  */
 public class SimpleRelinkableCallSite extends AbstractRelinkableCallSite {
     /**