1.1 --- a/src/jdk/internal/dynalink/DynamicLinker.java Mon Jun 08 17:59:32 2015 +0530
1.2 +++ b/src/jdk/internal/dynalink/DynamicLinker.java Mon Jun 08 10:28:04 2015 +0200
1.3 @@ -99,10 +99,12 @@
1.4 import jdk.internal.dynalink.support.RuntimeContextLinkRequestImpl;
1.5
1.6 /**
1.7 - * The linker for {@link RelinkableCallSite} objects. Users of it (scripting frameworks and language runtimes) have to
1.8 - * create a linker using the {@link DynamicLinkerFactory} and invoke its link method from the invokedynamic bootstrap
1.9 - * methods to set the target of all the call sites in the code they generate. Usual usage would be to create one class
1.10 - * per language runtime to contain one linker instance as:
1.11 + * The linker for {@link RelinkableCallSite} objects. Users of it (scripting
1.12 + * frameworks and language runtimes) have to create a linker using the
1.13 + * {@link DynamicLinkerFactory} and invoke its link method from the invokedynamic
1.14 + * bootstrap methods to set the target of all the call sites in the code they
1.15 + * generate. Usual usage would be to create one class per language runtime to
1.16 + * contain one linker instance as:
1.17 *
1.18 * <pre>
1.19 * class MyLanguageRuntime {
1.20 @@ -123,19 +125,27 @@
1.21 *
1.22 * Note how there are three components you will need to provide here:
1.23 * <ul>
1.24 - * <li>You're expected to provide a {@link GuardingDynamicLinker} for your own language. If your runtime doesn't
1.25 - * have its own language and/or object model (i.e. it's a generic scripting shell), you don't need to implement a
1.26 - * dynamic linker; you would simply not invoke the {@code setPrioritizedLinker} method on the factory, or even better,
1.27 - * simply use {@link DefaultBootstrapper}.</li>
1.28 - * <li>The performance of the programs can depend on your choice of the class to represent call sites. The above
1.29 - * example used {@link MonomorphicCallSite}, but you might want to use {@link ChainedCallSite} instead. You'll need to
1.30 - * experiment and decide what fits your language runtime the best. You can subclass either of these or roll your own if
1.31 - * you need to.</li>
1.32 - * <li>You also need to provide {@link CallSiteDescriptor}s to your call sites. They are immutable objects that contain
1.33 - * all the information about the call site: the class performing the lookups, the name of the method being invoked, and
1.34 - * the method signature. The library has a default {@link CallSiteDescriptorFactory} for descriptors that you can use,
1.35 - * or you can create your own descriptor classes, especially if you need to add further information (values passed in
1.36 + *
1.37 + * <li>You're expected to provide a {@link GuardingDynamicLinker} for your own
1.38 + * language. If your runtime doesn't have its own language and/or object model
1.39 + * (i.e., it's a generic scripting shell), you don't need to implement a dynamic
1.40 + * linker; you would simply not invoke the {@code setPrioritizedLinker} method
1.41 + * on the factory, or even better, simply use {@link DefaultBootstrapper}.</li>
1.42 + *
1.43 + * <li>The performance of the programs can depend on your choice of the class to
1.44 + * represent call sites. The above example used {@link MonomorphicCallSite}, but
1.45 + * you might want to use {@link ChainedCallSite} instead. You'll need to
1.46 + * experiment and decide what fits your language runtime the best. You can
1.47 + * subclass either of these or roll your own if you need to.</li>
1.48 + *
1.49 + * <li>You also need to provide {@link CallSiteDescriptor}s to your call sites.
1.50 + * They are immutable objects that contain all the information about the call
1.51 + * site: the class performing the lookups, the name of the method being invoked,
1.52 + * and the method signature. The library has a default {@link CallSiteDescriptorFactory}
1.53 + * for descriptors that you can use, or you can create your own descriptor
1.54 + * classes, especially if you need to add further information (values passed in
1.55 * additional parameters to the bootstrap method) to them.</li>
1.56 + *
1.57 * </ul>
1.58 *
1.59 * @author Attila Szegedi
1.60 @@ -176,11 +186,15 @@
1.61 }
1.62
1.63 /**
1.64 - * Links an invokedynamic call site. It will install a method handle into the call site that invokes the relinking
1.65 - * mechanism of this linker. Next time the call site is invoked, it will be linked for the actual arguments it was
1.66 - * invoked with.
1.67 + * Links an invokedynamic call site. It will install a method handle into
1.68 + * the call site that invokes the relinking mechanism of this linker. Next
1.69 + * time the call site is invoked, it will be linked for the actual arguments
1.70 + * it was invoked with.
1.71 *
1.72 + * @param <T> the particular subclass of {@link RelinkableCallSite} for
1.73 + * which to create a link.
1.74 * @param callSite the call site to link.
1.75 + *
1.76 * @return the callSite, for easy call chaining.
1.77 */
1.78 public <T extends RelinkableCallSite> T link(final T callSite) {
1.79 @@ -189,10 +203,13 @@
1.80 }
1.81
1.82 /**
1.83 - * Returns the object representing the lower level linker services of this class that are normally exposed to
1.84 - * individual language-specific linkers. While as a user of this class you normally only care about the
1.85 - * {@link #link(RelinkableCallSite)} method, in certain circumstances you might want to use the lower level services
1.86 - * directly; either to lookup specific method handles, to access the type converters, and so on.
1.87 + * Returns the object representing the lower level linker services of this
1.88 + * class that are normally exposed to individual language-specific linkers.
1.89 + * While as a user of this class you normally only care about the
1.90 + * {@link #link(RelinkableCallSite)} method, in certain circumstances you
1.91 + * might want to use the lower level services directly; either to lookup
1.92 + * specific method handles, to access the type converters, and so on.
1.93 + *
1.94 * @return the object representing the linker services of this class.
1.95 */
1.96 public LinkerServices getLinkerServices() {
1.97 @@ -218,7 +235,9 @@
1.98 *
1.99 * @param callSite the call site itself
1.100 * @param arguments arguments to the invocation
1.101 + *
1.102 * @return return the method handle for the invocation
1.103 + *
1.104 * @throws Exception rethrows any exception thrown by the linkers
1.105 */
1.106 @SuppressWarnings("unused")
1.107 @@ -272,11 +291,15 @@
1.108 }
1.109
1.110 /**
1.111 - * Returns a stack trace element describing the location of the call site currently being linked on the current
1.112 - * thread. The operation internally creates a Throwable object and inspects its stack trace, so it's potentially
1.113 - * expensive. The recommended usage for it is in writing diagnostics code.
1.114 - * @return a stack trace element describing the location of the call site currently being linked, or null if it is
1.115 - * not invoked while a call site is being linked.
1.116 + * Returns a stack trace element describing the location of the call site
1.117 + * currently being linked on the current thread. The operation internally
1.118 + * creates a Throwable object and inspects its stack trace, so it's
1.119 + * potentially expensive. The recommended usage for it is in writing
1.120 + * diagnostics code.
1.121 + *
1.122 + * @return a stack trace element describing the location of the call site
1.123 + * currently being linked, or null if it is not invoked while a call
1.124 + * site is being linked.
1.125 */
1.126 public static StackTraceElement getLinkedCallSiteLocation() {
1.127 final StackTraceElement[] trace = new Throwable().getStackTrace();
1.128 @@ -290,8 +313,10 @@
1.129 }
1.130
1.131 /**
1.132 - * Deprecated because of not precise name.
1.133 + * Deprecated because of imprecise name.
1.134 + *
1.135 * @deprecated Use {@link #getLinkedCallSiteLocation()} instead.
1.136 + *
1.137 * @return see non-deprecated method
1.138 */
1.139 @Deprecated
1.140 @@ -300,20 +325,26 @@
1.141 }
1.142
1.143 /**
1.144 - * Returns true if the frame represents {@code MethodHandleNatives.linkCallSite()}, the frame immediately on top of
1.145 - * the call site frame when the call site is being linked for the first time.
1.146 + * Returns {@code true} if the frame represents {@code MethodHandleNatives.linkCallSite()},
1.147 + * the frame immediately on top of the call site frame when the call site is
1.148 + * being linked for the first time.
1.149 + *
1.150 * @param frame the frame
1.151 - * @return true if this frame represents {@code MethodHandleNatives.linkCallSite()}
1.152 + *
1.153 + * @return {@code true} if this frame represents {@code MethodHandleNatives.linkCallSite()}.
1.154 */
1.155 private static boolean isInitialLinkFrame(final StackTraceElement frame) {
1.156 return testFrame(frame, INITIAL_LINK_METHOD_NAME, INITIAL_LINK_CLASS_NAME);
1.157 }
1.158
1.159 /**
1.160 - * Returns true if the frame represents {@code DynamicLinker.relink()}, the frame immediately on top of the call
1.161 - * site frame when the call site is being relinked (linked for second and subsequent times).
1.162 + * Returns {@code true} if the frame represents {@code DynamicLinker.relink()},
1.163 + * the frame immediately on top of the call site frame when the call site is
1.164 + * being relinked (linked for second and subsequent times).
1.165 + *
1.166 * @param frame the frame
1.167 - * @return true if this frame represents {@code DynamicLinker.relink()}
1.168 + *
1.169 + * @return {@code true} if this frame represents {@code DynamicLinker.relink()}.
1.170 */
1.171 private static boolean isRelinkFrame(final StackTraceElement frame) {
1.172 return testFrame(frame, RELINK_METHOD_NAME, CLASS_NAME);
