public abstract class LibraryFactory<T extends Library> extends Object
LibraryFactory.resolve(Class)
.
Library instances are either automatically dispatched or manually dispatched.
Automatically dispatched libraries always return true
for
Library.accepts(Object)
therefore they can be used with changing receiver values.
Manually dispatched libraries are created once for a receiver and are only valid as long as
accepts
returns true
. Once accepts was checked for
an individual value, it is guaranteed that the accepts continues to return true. It is therefore
not necessary to call accepts again for multiple message invocations. To create automatically
dispatched versions of libraries use either LibraryFactory.createDispatched(int)
or
LibraryFactory.getUncached()
. For calling manually dispatched libraries it is recommended to use
CachedLibrary
instead using the factory manually.
Library instances are either cached or uncached. Cached instances are library
instances designed to be used in ASTs. Cached instances are typically adoptable
and store additional profiling information for the cached export. This allows to
generate call-site specific profiling information for libray calls. Before a cached instance can
be used it must be adopted
by a parent node. Cached instances of
libraries have a cost
of NodeCost.MONOMORPHIC
for each manually
cached library.
Uncached versions are designed to be used from slow-path runtime methods or whenever call-site
specific profiling is not desired. All uncached versions of a library are annotated with
@TruffleBoundary. Uncached instances always return
false
for Node.isAdoptable()
. Uncached instances of libraries have a
cost
of NodeCost.MEGAMORPHIC
.
This class is intended to be sub-classed by generated code only. Do not sub-class
LibraryFactory
manually.
Library
,
LibraryExport
,
CachedLibrary
,
Message
Modifier | Constructor and Description |
---|---|
protected |
LibraryFactory(Class<T> libraryClass,
List<Message> messages)
Constructor for generated subclasses.
|
Modifier and Type | Method and Description |
---|---|
protected static boolean |
assertAdopted(Node node)
Internal method for generated code only.
|
T |
create(Object receiver)
Creates a new manually dispatched cached library for a given receiver.
|
protected T |
createAOT(LibraryExport<T> lib)
Creates an AOT version for a library export.
|
protected T |
createAssertions(T delegate)
Creates an assertion version of this library.
|
protected T |
createDelegate(T original)
Creates a delegate version of a library.
|
T |
createDispatched(int limit)
Creates a new cached and automatically dispatched library given a limit.
|
protected abstract T |
createDispatchImpl(int limit)
Creates a cached automatically dispatched version of this library.
|
protected FinalBitSet |
createMessageBitSet(Message... enabledMessages)
Creates a final bitset of the given messages.
|
protected abstract T |
createProxy(ReflectionLibrary lib)
Creates a proxy version of this library.
|
protected abstract T |
createUncachedDispatch()
Creates a uncached automatically dispatched version of this library.
|
protected abstract Object |
genericDispatch(Library library,
Object receiver,
Message message,
Object[] arguments,
int parameterOffset)
Performs a generic dispatch for this library.
|
protected List<LibraryExport<T>> |
getAOTExports()
Returns a list of ordered exports to be used for AOT preparation if supported.
|
protected abstract Class<?> |
getDefaultClass(Object receiver)
Returns default exported used for a given receiver.
|
protected static <T extends Library> |
getDelegateLibrary(T lib,
Object delegate)
Returns the delegated library to use when messages are delegated.
|
protected MethodHandles.Lookup |
getLookup()
Returns a method handle lookup used to initialize the library class.
|
List<Message> |
getMessages()
Returns an unmodifiable list of messages that this library provides.
|
T |
getUncached()
Returns an uncached automatically dispatched version of the library.
|
T |
getUncached(Object receiver)
Returns an uncached manually dispatched library for a given receiver.
|
protected static boolean |
isDelegated(Library lib,
int index)
Returns
true if a message is delegated, otherwise false . |
protected static Object |
readDelegate(Library lib,
Object receiver)
Reads the delegate for a receiver.
|
protected static <T extends Library> |
register(Class<T> libraryClass,
LibraryFactory<T> library) |
static <T extends Library> |
resolve(Class<T> library)
Looks up the resolved library instance for a library class.
|
String |
toString() |
protected LibraryFactory(Class<T> libraryClass, List<Message> messages)
LibraryFactory
manually.public final T createDispatched(int limit)
IllegalArgumentException
. It is discouraged to use Integer.MAX_VALUE
as
parameter to this method. Reasonable values for the limit range from zero to ten.
If possible it is recommended to not use this method manually but to use
CachedLibrary
instead.
Whenever the limit is reached for a node and the uncached version is in use, the current
enclosing node will be available to the uncached library export of the library using
EncapsulatingNodeReference
.
EncapsulatingNodeReference
,
CachedLibrary
public final T create(Object receiver)
null
. The returned library must be adopted before used. For calling manually
dispatched libraries it is recommended to use CachedLibrary
instead using the factory
manually.CachedLibrary
protected final T createAOT(LibraryExport<T> lib)
public final T getUncached()
public final T getUncached(Object receiver)
null
.CachedLibrary
public final List<Message> getMessages()
message ids
.protected static boolean assertAdopted(Node node)
protected abstract T createDispatchImpl(int limit)
protected final List<LibraryExport<T>> getAOTExports()
protected abstract T createUncachedDispatch()
protected abstract T createProxy(ReflectionLibrary lib)
protected T createDelegate(T original)
protected T createAssertions(T delegate)
protected abstract Class<?> getDefaultClass(Object receiver)
protected MethodHandles.Lookup getLookup()
protected abstract Object genericDispatch(Library library, Object receiver, Message message, Object[] arguments, int parameterOffset) throws Exception
Exception
protected FinalBitSet createMessageBitSet(Message... enabledMessages)
protected static boolean isDelegated(Library lib, int index)
true
if a message is delegated, otherwise false
. Intended
to be used by generated code only, do not use manually.protected static Object readDelegate(Library lib, Object receiver)
protected static <T extends Library> T getDelegateLibrary(T lib, Object delegate)
public static <T extends Library> LibraryFactory<T> resolve(Class<T> library)
IllegalArgumentException
is thrown.Library
protected static <T extends Library> void register(Class<T> libraryClass, LibraryFactory<T> library)