LibraryFactory (GraalVM Truffle Java API Reference)

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 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.

Since:

19.0

See Also:

Library, LibraryExport, CachedLibrary, Message

Constructor Summary

Constructors
Modifier Constructor and Description

protected LibraryFactory(Class<T> libraryClass, List<Message> messages)
Constructor for generated subclasses.

Constructors
Modifier	Constructor and Description
`protected`	`LibraryFactory(Class<T> libraryClass, List<Message> messages)` Constructor for generated subclasses.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
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> T`	`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> void`	`register(Class<T> libraryClass, LibraryFactory<T> library)`
`static <T extends Library> LibraryFactory<T>`	`resolve(Class<T> library)` Looks up the resolved library instance for a library class.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - LibraryFactory
```
protected LibraryFactory(Class<T> libraryClass,
                         List<Message> messages)
```
    Constructor for generated subclasses. Do not sub-class LibraryFactory manually.
    
    Since:
    
    19.0
- Method Detail
  - 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:
    
    EncapsulatingNodeReference, CachedLibrary
  - 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:
    
    CachedLibrary
  - 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:
    
    CachedLibrary
  - 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:
    
    Library
  - 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

Class LibraryFactory<T extends Library>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LibraryFactory

Method Detail

createDispatched

create

createAOT

getUncached

getUncached

getMessages

assertAdopted

createDispatchImpl

getAOTExports

createUncachedDispatch

createProxy

createDelegate

createAssertions

getDefaultClass

getLookup

genericDispatch

createMessageBitSet

isDelegated

readDelegate

getDelegateLibrary

resolve

register

toString