Package com.oracle.truffle.api.library

Class LibraryFactory<T extends Library>

java.lang.Object
com.oracle.truffle.api.library.LibraryFactory<T>
public abstract class LibraryFactory<T extends Library> extends Object
Library factories allow to create instances of libraries used to call library messages. A library factory for a library class can be looked up using the static method 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 createDispatched(int) or 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.

Since:
19.0
See Also:

  • Constructor Details

    • LibraryFactory

      protected LibraryFactory(Class<T> libraryClass, List<Message> messages)
      Constructor for generated subclasses. Do not sub-class LibraryFactory manually.
      Since:
      19.0

  • Method Details

    • createDispatched

      public final T createDispatched(int limit)
      Creates a new cached and automatically dispatched library given a limit. The limit specifies the number of cached instances that will be automatically dispatched until the dispatched library rewrites itself to an uncached version of the library. If the limit is zero then the library will use an uncached version from the start. Negative values will throw an 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.

      Since:
      19.0
      See Also:

    • create

      public final T create(Object receiver)
      Creates a new manually dispatched cached library for a given receiver. The receiver must not be 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.
      Since:
      19.0
      See Also:

    • createAOT

      protected final T createAOT(LibraryExport<T> lib)
      Creates an AOT version for a library export. Intended to be used by generated code, do not use manually.
      Since:
      21.2

    • getUncached

      public final T getUncached()
      Returns an uncached automatically dispatched version of the library. This is version of a library is used for slow-path calls.
      Since:
      19.0

    • getUncached

      public final T getUncached(Object receiver)
      Returns an uncached manually dispatched library for a given receiver. The receiver must not be null.
      Since:
      19.0
      See Also:

    • getMessages

      public final List<Message> getMessages()
      Returns an unmodifiable list of messages that this library provides. The returned list is ordered by message ids.
      Since:
      22.0

    • assertAdopted

      protected static boolean assertAdopted(Node node)
      Internal method for generated code only.
      Since:
      23.1

    • createDispatchImpl

      protected abstract T createDispatchImpl(int limit)
      Creates a cached automatically dispatched version of this library. An implementation for this method is generated, do not implement or call manually.
      Since:
      19.0

    • getAOTExports

      protected final List<LibraryExport<T>> getAOTExports()
      Returns a list of ordered exports to be used for AOT preparation if supported. Intended to be used by generated code only, do not use manually.
      Since:
      21.2

    • createUncachedDispatch

      protected abstract T createUncachedDispatch()
      Creates a uncached automatically dispatched version of this library. An implementation for this method is generated, do not implement or call manually.
      Since:
      19.0

    • createProxy

      protected abstract T createProxy(ReflectionLibrary lib)
      Creates a proxy version of this library. A proxy version is responsible for dispatching to reflective implementations of messages. An implementation for this method is generated, do not implement manually.
      Since:
      19.0

    • createDelegate

      protected T createDelegate(T original)
      Creates a delegate version of a library. May be used for cached or uncached versions of a library. Intended to be used by generated code only, do not use manually.
      Since:
      20.0

    • createAssertions

      protected T createAssertions(T delegate)
      Creates an assertion version of this library. An implementation for this method is generated, do not implement manually.
      Since:
      19.0

    • getDefaultClass

      protected abstract Class<?> getDefaultClass(Object receiver)
      Returns default exported used for a given receiver. An implementation for this method is generated, do not implement manually.
      Since:
      19.0

    • getLookup

      protected MethodHandles.Lookup getLookup()
      Returns a method handle lookup used to initialize the library class.
      Since:
      24.0

    • genericDispatch

      protected abstract Object genericDispatch(Library library, Object receiver, Message message, Object[] arguments, int parameterOffset) throws Exception
      Performs a generic dispatch for this library. An implementation for this method is generated, do not implement manually.
      Throws:
      Exception
      Since:
      19.0

    • createMessageBitSet

      protected FinalBitSet createMessageBitSet(Message... enabledMessages)
      Creates a final bitset of the given messages. Uses an internal index for the messages. An implementation for this method is generated, do not implement manually.
      Since:
      20.0

    • isDelegated

      protected static boolean isDelegated(Library lib, int index)
      Returns true if a message is delegated, otherwise false. Intended to be used by generated code only, do not use manually.
      Since:
      20.0

    • readDelegate

      protected static Object readDelegate(Library lib, Object receiver)
      Reads the delegate for a receiver. Intended to be used by generated code only, do not use manually.
      Since:
      20.0

    • getDelegateLibrary

      protected static <T extends Library> T getDelegateLibrary(T lib, Object delegate)
      Returns the delegated library to use when messages are delegated. Intended to be used by generated code only, do not use manually.
      Since:
      20.0

    • resolve

      public static <T extends Library> LibraryFactory<T> resolve(Class<T> library)
      Looks up the resolved library instance for a library class. If a library class was not yet loaded it will be initialized automatically. If the passed library class is not a valid library then a IllegalArgumentException is thrown.
      Since:
      19.0
      See Also:

    • register

      protected static <T extends Library> void register(Class<T> libraryClass, LibraryFactory<T> library)
      Since:
      19.0

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Since:
      19.0