org.dynalang.dynalink

Class DynamicLinker

java.lang.Object

org.dynalang.dynalink.DynamicLinker

public class DynamicLinker
extends Object

The linker for RelinkableCallSite objects. Users of it (scripting frameworks and language runtimes) have to create a linker using the DynamicLinkerFactory and invoke its link method from the invokedynamic bootstrap methods to set the target of all the call sites in the code they generate. Usual usage would be to create one class per language runtime to contain one linker instance as:

 class MyLanguageRuntime {
     private static final GuardingDynamicLinker myLanguageLinker = new MyLanguageLinker();
     private static final DynamicLinker dynamicLinker = createDynamicLinker();

     private static DynamicLinker createDynamicLinker() {
         final DynamicLinkerFactory factory = new DynamicLinkerFactory();
         factory.setPrioritizedLinker(myLanguageLinker);
         return factory.createLinker();
     }

     public static CallSite bootstrap(MethodHandles.Lookup caller, String name, MethodType type) {
         return dynamicLinker.link(new MonomorphicCallSite(CallSiteDescriptorFactory.create(lookup, name, type)));
     }
 }
 

Note how there are three components you will need to provide here:

• You're expected to provide a GuardingDynamicLinker for your own language. If your runtime doesn't have its own language and/or object model (i.e. it's a generic scripting shell), you don't need to implement a dynamic linker; you would simply not invoke the setPrioritizedLinker method on the factory, or even better, simply use DefaultBootstrapper.
• The performance of the programs can depend on your choice of the class to represent call sites. The above example used MonomorphicCallSite, but you might want to use ChainedCallSite instead. You'll need to experiment and decide what fits your language runtime the best. You can subclass either of these or roll your own if you need to.
• You also need to provide CallSiteDescriptors to your call sites. They are immutable objects that contain all the information about the call site: the class performing the lookups, the name of the method being invoked, and the method signature. The library has a default CallSiteDescriptorFactory for descriptors that you can use, or you can create your own descriptor classes, especially if you need to add further information (values passed in additional parameters to the bootstrap method) to them.

Author:

Attila Szegedi

Method Summary

Modifier and Type	Method and Description
static StackTraceElement	getLinkedCallSiteLocation() Returns a stack trace element describing the location of the call site currently being linked on the current thread.
LinkerServices	getLinkerServices() Returns the object representing the lower level linker services of this class that are normally exposed to individual language-specific linkers.
static StackTraceElement	getRelinkedCallSiteLocation() Deprecated. Use getLinkedCallSiteLocation() instead.
<T extends RelinkableCallSite> T	link(T callSite) Links an invokedynamic call site.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

link

public <T extends RelinkableCallSite> T link(T callSite)

Links an invokedynamic call site. It will install a method handle into the call site that invokes the relinking mechanism of this linker. Next time the call site is invoked, it will be linked for the actual arguments it was invoked with.

Parameters:

callSite - the call site to link.

Returns:

the callSite, for easy call chaining.

getLinkerServices

public LinkerServices getLinkerServices()

Returns the object representing the lower level linker services of this class that are normally exposed to individual language-specific linkers. While as a user of this class you normally only care about the link(RelinkableCallSite) method, in certain circumstances you might want to use the lower level services directly; either to lookup specific method handles, to access the type converters, and so on.

Returns:

the object representing the linker services of this class.

getLinkedCallSiteLocation

public static StackTraceElement getLinkedCallSiteLocation()

Returns a stack trace element describing the location of the call site currently being linked on the current thread. The operation internally creates a Throwable object and inspects its stack trace, so it's potentially expensive. The recommended usage for it is in writing diagnostics code.

Returns:

a stack trace element describing the location of the call site currently being linked, or null if it is not invoked while a call site is being linked.

getRelinkedCallSiteLocation

@Deprecated
public static StackTraceElement getRelinkedCallSiteLocation()

Deprecated. Use getLinkedCallSiteLocation() instead.

Deprecated because of not precise name.

Returns:

see non-deprecated method