Class InteropLibrary

All Implemented Interfaces:
NodeInterface, Cloneable

public abstract class InteropLibrary extends Library
Represents the library that specifies the interoperability message protocol between Truffle languages, tools and embedders. Every method represents one message specified by the protocol. In the following text we will abbreviate interoperability with interop.

The interop API differentiates between the source and the target language. The source language is the language that implements/exports the message implementations. The implementations map types of the source language to the interop protocol as it is specified by the protocol. For example, language values that represent arrays or array like structures should implement the messages for array based access. This allows the target language to call the protocol without knowledge of the concrete source language. The target language embeds the interop protocol semantics as part of their existing language semantics. For example, language operations that access array elements in the target language should call array access messages for interop values.

The interop protocol only allows interop values to be used as receivers, return values or parameters of messages. Allowed Java types of interop values are:

Note that null is never a valid interop value. Instead, use a TruffleObject which implements isNull(Object) message.

The following type combinations are mutually exclusive and cannot return true for the type check message of the same receiver value:

All receiver values may have none, one or multiple of the following traits:

Naive and aware dates and times

If a date or time value has a timezone then it is called aware , otherwise naive

An aware time and date has sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, to locate itself relative to other aware objects. An aware object is used to represent a specific moment in time that is not open to interpretation.

A naive time and date does not contain enough information to unambiguously locate itself relative to other date/time objects. Whether a naive object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, just like it is up to the program whether a particular number represents metres, miles, or mass. Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.

Interop messages throw checked exceptions to indicate error states. The target language is supposed to always catch those exceptions and translate them into guest language errors of the target language. Interop message contracts are verified only if assertions (-ea) are enabled.

See Also: