com.oracle.truffle.api.library

Annotation Type GenerateLibrary

@Retention(value=CLASS)
 @Target(value=TYPE)
public @interface GenerateLibrary

Libraries are specified with public and abstract Java classes that extend the Library class and are annotated by @GenerateLibrary. A library consists of a set of messages, that are specified using public Java methods. The methods may be abstract or use default implementations. The first parameter of every library message is the receiver parameter, which must be a non-primitive type and consistent across all messages of a library. There are no restrictions on the return type or argument types of a message. Every method that specifies a message must have a name that is unique per library. Final or private methods will always be ignored by the generator. Parameter type overloading is currently not supported for messages, therefore every public method must have a unique name per library. Generic type arguments local to messages are generally supported, but generic type arguments on the library type are not yet supported.

Basic Usage

The following example specifies a basic library for arrays:

 @GenerateLibrary
 public abstract class ArrayLibrary extends Library {

     public boolean isArray(Object receiver) {
         return false;
     }

     public abstract int read(Object receiver, int index);
 }
 

Messages that are not implemented and have no default implementation throw an AbstractMethodError. The GenerateLibrary.Abstract annotation can be used, to provide a default implementation for receiver types but at the same time make the message abstract.

A library class may also specify default exports that can be used to dispatch to receiver types that don't export the library. Since the receiver type for default exports can be specified explicitly, it can be used to provide a default implementation for receiver types of third parties or the JDK. For example the Truffle interop library has default exports for most Number types, String and Boolean type.

Since:

19.0

See Also:

to specify default exports., to make messages abstract if they have a default implemetnation

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<? extends Library>	assertions Specifies an assertion wrapper class that can be used to verify pre and post conditions of a library.
Class<?>	receiverType Restricts the receiver type for exports that implement this library.

Element Detail

assertions

public abstract Class<? extends Library> assertions

Specifies an assertion wrapper class that can be used to verify pre and post conditions of a library. Assertion wrappers are only inserted when assertions (-ea) are enabled. It is required that assertion wrappers don't introduce additional side-effects and call the delegate methods exactly once. If assertions are disabled no library wrapper will be inserted therefore not performing any checks when library messages are invoked.

Example Usage:

 @GenerateLibrary(assertions = ArrayAssertions.class)
 public abstract class ArrayLibrary extends Library {

     public boolean isArray(Object receiver) {
         return false;
     }

     public int read(Object receiver, int index) {
         throw new UnsupportedOperationException();
     }

     static class ArrayAssertions extends ArrayLibrary {

         @Child private ArrayLibrary delegate;

         ArrayAssertions(ArrayLibrary delegate) {
             this.delegate = delegate;
         }

         @Override
         public boolean isArray(Object receiver) {
             return delegate.isArray(receiver);
         }

         @Override
         public int read(Object receiver, int index) {
             int result = super.read(receiver, index);
             assert delegate.isArray(receiver) : "if a read was successful the receiver must be an array";
             return result;
         }

         @Override
         public boolean accepts(Object receiver) {
             return delegate.accepts(receiver);
         }
     }
 }

 

Since:

19.0

Default:

com.oracle.truffle.api.library.Library.class

receiverType

public abstract Class<?> receiverType

Restricts the receiver type for exports that implement this library. This allows to have different receiver type in message methods, but require export receiver types to implement or extend a declared class. Default exports are not affected by this restriction and can therefore export the library for any receiver type the message methods first parameter is compatible with.

Since:

19.0

Default:

java.lang.Object.class