public final class DynamicLinkerFactory extends Object
DynamicLinker
objects. Dynamic linkers
are the central objects in Dynalink; these are composed of several
GuardingDynamicLinker
objects and coordinate linking of call sites
with them. The usual dynamic linker is a linker
composed of all GuardingDynamicLinker
objects explicitly pre-created
by the user of the factory and configured with
setPrioritizedLinkers(List)
, as well as any
automatically discovered
ones, and
finally the ones configured with setFallbackLinkers(List)
; this last
category usually includes BeansLinker
.Constructor and Description |
---|
DynamicLinkerFactory()
Creates a new dynamic linker factory with default configuration.
|
Modifier and Type | Method and Description |
---|---|
DynamicLinker |
createLinker()
Creates a new dynamic linker based on the current configuration.
|
List<ServiceConfigurationError> |
getAutoLoadingErrors()
Returns a list of
ServiceConfigurationError s that were
encountered while loading automatically discovered linkers during the
last invocation of createLinker() . |
void |
setAutoConversionStrategy(MethodTypeConversionStrategy autoConversionStrategy)
Sets an object representing the conversion strategy for automatic type
conversions.
|
void |
setClassLoader(ClassLoader classLoader)
Sets the class loader for automatic discovery of available guarding
dynamic linkers.
|
void |
setFallbackLinkers(List<? extends GuardingDynamicLinker> fallbackLinkers)
Sets the fallback guarding dynamic linkers.
|
void |
setFallbackLinkers(GuardingDynamicLinker... fallbackLinkers)
Sets the fallback guarding dynamic linkers.
|
void |
setInternalObjectsFilter(MethodHandleTransformer internalObjectsFilter)
Sets a method handle transformer that is supposed to act as the
implementation of
LinkerServices.filterInternalObjects(MethodHandle) for linker
services of dynamic linkers created by this factory. |
void |
setPrelinkTransformer(GuardedInvocationTransformer prelinkTransformer)
Set the pre-link transformer.
|
void |
setPrioritizedLinker(GuardingDynamicLinker prioritizedLinker)
Sets a single prioritized linker.
|
void |
setPrioritizedLinkers(List<? extends GuardingDynamicLinker> prioritizedLinkers)
Sets the prioritized guarding dynamic linkers.
|
void |
setPrioritizedLinkers(GuardingDynamicLinker... prioritizedLinkers)
Sets the prioritized guarding dynamic linkers.
|
void |
setSyncOnRelink(boolean syncOnRelink)
Sets whether the dynamic linker created by this factory will invoke
MutableCallSite.syncAll(MutableCallSite[]) after a call site is
relinked. |
void |
setUnstableRelinkThreshold(int unstableRelinkThreshold)
Sets the unstable relink threshold; the number of times a call site is
relinked after which it will be considered unstable, and subsequent link
requests for it will indicate this.
|
public DynamicLinkerFactory()
setXxx()
methods and used to create one or more dynamic linkers according to its
current configuration using createLinker()
.public void setClassLoader(ClassLoader classLoader)
GuardingDynamicLinkerExporter
implementations
available through this class loader will be automatically instantiated
using the ServiceLoader
mechanism and the linkers they provide
will be incorporated into DynamicLinker
s that this factory
creates. This allows for cross-language interoperability where call sites
belonging to this language runtime can be linked by linkers from these
automatically discovered runtimes if their native objects are passed to
this runtime. If class loader is not set explicitly by invoking this
method, then the thread context class loader of the thread invoking
createLinker()
will be used. If this method is invoked
explicitly with null then ServiceLoader.loadInstalled(Class)
will
be used to load the linkers.classLoader
- the class loader used for the automatic discovery of
available linkers.public void setPrioritizedLinkers(List<? extends GuardingDynamicLinker> prioritizedLinkers)
prioritizedLinkers
- the list of prioritized linkers. Can be null.NullPointerException
- if any of the list elements are null.public void setPrioritizedLinkers(GuardingDynamicLinker... prioritizedLinkers)
setPrioritizedLinkers(List)
with
Arrays.asList(prioritizedLinkers)
.prioritizedLinkers
- an array of prioritized linkers. Can be null.NullPointerException
- if any of the array elements are null.public void setPrioritizedLinker(GuardingDynamicLinker prioritizedLinker)
setPrioritizedLinkers(List)
with a single-element list.prioritizedLinker
- the single prioritized linker. Must not be null.NullPointerException
- if null is passed.public void setFallbackLinkers(List<? extends GuardingDynamicLinker> fallbackLinkers)
fallbackLinkers
- the list of fallback linkers. Can be empty to
indicate the caller wishes to set no fallback linkers. Note that if this
method is not invoked explicitly or is passed null, then the factory
will create an instance of BeansLinker
to serve as the default
fallback linker.NullPointerException
- if any of the list elements are null.public void setFallbackLinkers(GuardingDynamicLinker... fallbackLinkers)
setFallbackLinkers(List)
with
Arrays.asList(fallbackLinkers)
.fallbackLinkers
- an array of fallback linkers. Can be empty to
indicate the caller wishes to set no fallback linkers. Note that if this
method is not invoked explicitly or is passed null, then the factory
will create an instance of BeansLinker
to serve as the default
fallback linker.NullPointerException
- if any of the array elements are null.public void setSyncOnRelink(boolean syncOnRelink)
MutableCallSite.syncAll(MutableCallSite[])
after a call site is
relinked. Defaults to false. You probably want to set it to true if your
runtime supports multithreaded execution of dynamically linked code.syncOnRelink
- true for invoking sync on relink, false otherwise.public void setUnstableRelinkThreshold(int unstableRelinkThreshold)
unstableRelinkThreshold
- the new threshold. Must not be less than
zero. The value of zero means that call sites will never be considered
unstable.LinkRequest.isCallSiteUnstable()
public void setPrelinkTransformer(GuardedInvocationTransformer prelinkTransformer)
GuardedInvocationTransformer
that will get the final chance to
modify the guarded invocation after it has been created by a component
linker and before the dynamic linker links it into the call site. It is
normally used to adapt the return value type of the invocation to the
type of the call site. When not set explicitly, a default pre-link
transformer will be used that simply calls
GuardedInvocation.asType(LinkerServices, MethodType)
. Customized
pre-link transformers are rarely needed; they are mostly used as a
building block for implementing advanced techniques such as code
deoptimization strategies.prelinkTransformer
- the pre-link transformer for the dynamic
linker. Can be null to have the factory use the default transformer.public void setAutoConversionStrategy(MethodTypeConversionStrategy autoConversionStrategy)
LinkerServices.asType(MethodHandle, MethodType)
has applied all
custom conversions to a method handle, it still needs to effect
method
invocation conversions
that can usually be automatically applied as per
MethodHandle.asType(MethodType)
. However, sometimes language
runtimes will want to customize even those conversions for their own call
sites. A typical example is allowing unboxing of null return values,
which is by default prohibited by ordinary
MethodHandles.asType()
. In this case, a language runtime can
install its own custom automatic conversion strategy, that can deal with
null values. Note that when the strategy's
MethodTypeConversionStrategy.asType(MethodHandle, MethodType)
is invoked, the custom language conversions will already have been
applied to the method handle, so by design the difference between the
handle's current method type and the desired final type will always only
be ones that can be subjected to method invocation conversions. The
strategy also doesn't need to invoke a final
MethodHandle.asType()
as that will be done internally as the
final step.autoConversionStrategy
- the strategy for applying method invocation
conversions for the linker created by this factory. Can be null for no
custom strategy.public void setInternalObjectsFilter(MethodHandleTransformer internalObjectsFilter)
LinkerServices.filterInternalObjects(MethodHandle)
for linker
services of dynamic linkers created by this factory. Some language
runtimes can have internal objects that should not escape their scope.
They can add a transformer here that will modify the method handle so
that any parameters that can receive potentially internal language
runtime objects will have a filter added on them to prevent them from
escaping, potentially by wrapping them. The transformer can also
potentially add an unwrapping filter to the return value.
DefaultInternalObjectFilter
is provided as a convenience class
for easily creating such filtering transformers.internalObjectsFilter
- a method handle transformer filtering out
internal objects, or null.public DynamicLinker createLinker()
getAutoLoadingErrors()
to
retrieve a list of ServiceConfigurationError
s that occurred while
trying to load automatically discovered linkers. These are never thrown
from the call to this method as it makes every effort to recover from
them and ignore the failing linkers.public List<ServiceConfigurationError> getAutoLoadingErrors()
ServiceConfigurationError
s that were
encountered while loading automatically discovered linkers during the
last invocation of createLinker()
. They can be any non-Dynalink
specific service configuration issues, as well as some Dynalink-specific
errors when an exporter that the factory tried to automatically load:
GuardingDynamicLinkerExporter.AUTOLOAD_PERMISSION_NAME
in a
system with a security manager, orSupplier.get()
, orSupplier.get()
had a null element.ServiceConfigurationError
s. Can be empty.
Copyright © 2015, 2016, Oracle and/or its affiliates. All rights reserved.
DRAFT 9-internal+0-2016-03-31-172659.buildd.src