com.oracle.truffle.api.interop

Class ForeignAccess

java.lang.Object

com.oracle.truffle.api.interop.ForeignAccess

public final class ForeignAccess
extends Object

Encapsulates types of access to TruffleObject. If you want to expose your own objects to foreign language implementations, you need to implement TruffleObject and its TruffleObject.getForeignAccess() method. To create instance of ForeignAccess , use one of the factory methods available in this class.

Since:

0.8 or earlier

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ForeignAccess.Factory Interface of a factory that produces AST snippets that can access a foreign TruffleObject.
static interface	ForeignAccess.StandardFactory Specialized factory that handles standard foreign messages.

Method Summary

Modifier and Type	Method and Description
static ForeignAccess	create(Class<? extends TruffleObject> baseClass, ForeignAccess.StandardFactory factory) Creates new instance of ForeignAccess that delegates to provided factory.
static ForeignAccess	create(ForeignAccess.Factory factory) Creates new instance of ForeignAccess that delegates to provided factory.
static ForeignAccess	create(ForeignAccess.StandardFactory factory, RootNode languageCheck) Creates new instance of ForeignAccess that delegates to provided factory.
static List<Object>	getArguments(Frame frame) Read only access to foreign call arguments inside of a frame.
static TruffleObject	getReceiver(Frame frame) The foreign receiver in the frame.
static Object	send(Node foreignNode, TruffleObject receiver, Object... arguments) Sends a Message to the foreign receiver object by executing the foreign node.
static long	sendAsPointer(Node asPointerNode, TruffleObject receiver) Sends an AS_POINTER message to the foreign receiver object by executing the asPointerNode .
static Object	sendExecute(Node executeNode, TruffleObject receiver, Object... arguments) Sends an EXECUTE Message to the foreign receiver object by executing the executeNode .
static Object	sendGetSize(Node getSizeNode, TruffleObject receiver) Sends a GET_SIZE message to the foreign receiver object by executing the getSizeNode .
static boolean	sendHasKeys(Node hasKeysNode, TruffleObject receiver) Sends an HAS_KEYS message to the foreign receiver object by executing the hasKeysNode.
static boolean	sendHasSize(Node hasSizeNode, TruffleObject receiver) Sends an HAS_SIZE message to the foreign receiver object by executing the hasSizeNode .
static Object	sendInvoke(Node invokeNode, TruffleObject receiver, String identifier, Object... arguments) Sends an INVOKE Message to the foreign receiver object by executing the invokeNode .
static boolean	sendIsBoxed(Node isBoxedNode, TruffleObject receiver) Sends an IS_BOXED message to the foreign receiver object by executing the isNullNode .
static boolean	sendIsExecutable(Node isExecutableNode, TruffleObject receiver) Sends an IS_EXECUTABLE message to the foreign receiver object by executing the isExecutableNode .
static boolean	sendIsInstantiable(Node isInstantiableNode, TruffleObject receiver) Sends an IS_INSTANTIABLE message to the foreign receiver object by executing the isInstantiableNode.
static boolean	sendIsNull(Node isNullNode, TruffleObject receiver) Sends an IS_NULL message to the foreign receiver object by executing the isNullNode .
static boolean	sendIsPointer(Node isPointerNode, TruffleObject receiver) Sends an IS_POINTER message to the foreign receiver object by executing the isPointerNode .
static int	sendKeyInfo(Node keyInfoNode, TruffleObject receiver, Object identifier) Sends a KEY_INFO message to the foreign receiver object by executing the keyInfoNode.
static TruffleObject	sendKeys(Node keysNode, TruffleObject receiver) Sends a Message.KEYS message to the foreign receiver object.
static TruffleObject	sendKeys(Node keysNode, TruffleObject receiver, boolean includeInternal) Sends a Message.KEYS message to the foreign receiver object, with a specification of whether internal keys should be included in the result, or not.
static Object	sendNew(Node newNode, TruffleObject receiver, Object... arguments) Sends an NEW Message to the foreign receiver object by executing the newNode .
static Object	sendRead(Node readNode, TruffleObject receiver, Object identifier) Sends a READ message to the foreign receiver object by executing the readNode .
static boolean	sendRemove(Node removeNode, TruffleObject receiver, Object identifier) Sends a REMOVE message to the foreign receiver object by executing the removeNode .
static Object	sendToNative(Node toNativeNode, TruffleObject receiver) Sends an TO_NATIVE message to the foreign receiver object by executing the toNativeNode .
static Object	sendUnbox(Node unboxNode, TruffleObject receiver) Sends an UNBOX message to the foreign receiver object by executing the unboxNode .
static Object	sendWrite(Node writeNode, TruffleObject receiver, Object identifier, Object value) Sends a WRITE message to the foreign receiver object by executing the writeNode .
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

create

public static ForeignAccess create(Class<? extends TruffleObject> baseClass,
                                   ForeignAccess.StandardFactory factory)

Creates new instance of ForeignAccess that delegates to provided factory.

Parameters:

baseClass - the super class of all TruffleObjects handled by this factory (if null then the second interface must also implement ForeignAccess.Factory)

factory - the factory that handles access requests to Messages

Returns:

new instance wrapping factory

Since:

0.30

create

public static ForeignAccess create(ForeignAccess.StandardFactory factory,
                                   RootNode languageCheck)

Creates new instance of ForeignAccess that delegates to provided factory.

Parameters:

factory - the factory that handles access requests to Messages

languageCheck - a RootNode that performs the language check on receiver objects, can be null, but then the factory must also implement ForeignAccess.Factory interface

Returns:

new instance wrapping factory

Since:

0.30

create

public static ForeignAccess create(ForeignAccess.Factory factory)

Creates new instance of ForeignAccess that delegates to provided factory.

Parameters:

factory - the factory that handles various access requests Messages.

Returns:

new instance wrapping factory

Since:

0.8 or earlier

send

public static Object send(Node foreignNode,
                          TruffleObject receiver,
                          Object... arguments)
                   throws InteropException

Sends a Message to the foreign receiver object by executing the foreign node.

Parameters:

foreignNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

arguments - parameters for the receiver

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

InteropException - if any error occurred while accessing the receiver object

Since:

0.24

sendRead

public static Object sendRead(Node readNode,
                              TruffleObject receiver,
                              Object identifier)
                       throws UnknownIdentifierException,
                              UnsupportedMessageException

Sends a READ message to the foreign receiver object by executing the readNode .

Parameters:

readNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

identifier - name of the property to be read

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by readNode

UnknownIdentifierException - if the receiver does not allow reading a property for the given identifier

Since:

0.24

sendWrite

public static Object sendWrite(Node writeNode,
                               TruffleObject receiver,
                               Object identifier,
                               Object value)
                        throws UnknownIdentifierException,
                               UnsupportedTypeException,
                               UnsupportedMessageException

Sends a WRITE message to the foreign receiver object by executing the writeNode .

Parameters:

writeNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

identifier - name of the property to be written

value - value to be written

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by writeNode

UnknownIdentifierException - if the receiver does not allow writing a property for the given identifier

UnsupportedTypeException - if value has an unsupported type

Since:

0.24

sendRemove

public static boolean sendRemove(Node removeNode,
                                 TruffleObject receiver,
                                 Object identifier)
                          throws UnknownIdentifierException,
                                 UnsupportedMessageException

Sends a REMOVE message to the foreign receiver object by executing the removeNode .

Parameters:

removeNode - the node created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

identifier - name of the property to be removed

Returns:

true if the property was successfully removed, false otherwise

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by readNode

UnknownIdentifierException - if the receiver does not allow removing a property for the given identifier

Since:

0.32

sendUnbox

public static Object sendUnbox(Node unboxNode,
                               TruffleObject receiver)
                        throws UnsupportedMessageException

Sends an UNBOX message to the foreign receiver object by executing the unboxNode .

Parameters:

unboxNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by unboxNode

Since:

0.24

sendIsPointer

public static boolean sendIsPointer(Node isPointerNode,
                                    TruffleObject receiver)

Sends an IS_POINTER message to the foreign receiver object by executing the isPointerNode .

Parameters:

isPointerNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.26

sendAsPointer

public static long sendAsPointer(Node asPointerNode,
                                 TruffleObject receiver)
                          throws UnsupportedMessageException

Sends an AS_POINTER message to the foreign receiver object by executing the asPointerNode .

Parameters:

asPointerNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

a raw 64bit pointer value

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by asPointerNode

Since:

0.26

sendToNative

public static Object sendToNative(Node toNativeNode,
                                  TruffleObject receiver)
                           throws UnsupportedMessageException

Sends an TO_NATIVE message to the foreign receiver object by executing the toNativeNode .

Parameters:

toNativeNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by toNativeNode

Since:

0.26

sendExecute

public static Object sendExecute(Node executeNode,
                                 TruffleObject receiver,
                                 Object... arguments)
                          throws UnsupportedTypeException,
                                 ArityException,
                                 UnsupportedMessageException

Sends an EXECUTE Message to the foreign receiver object by executing the executeNode .

Parameters:

executeNode - the createNode created by Message.createNode()

receiver - foreign function object to receive the message passed to Message.createNode() method

arguments - arguments passed to the foreign function

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedTypeException - if one of element of the arguments has an unsupported type

ArityException - if the arguments array does not contain the right number of arguments for the foreign function

UnsupportedMessageException - if the receiver does not support the message represented by executeNode

Since:

0.24

sendIsExecutable

public static boolean sendIsExecutable(Node isExecutableNode,
                                       TruffleObject receiver)

Sends an IS_EXECUTABLE message to the foreign receiver object by executing the isExecutableNode .

Parameters:

isExecutableNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.24

sendIsInstantiable

public static boolean sendIsInstantiable(Node isInstantiableNode,
                                         TruffleObject receiver)

Sends an IS_INSTANTIABLE message to the foreign receiver object by executing the isInstantiableNode.

Parameters:

isInstantiableNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.30

sendInvoke

public static Object sendInvoke(Node invokeNode,
                                TruffleObject receiver,
                                String identifier,
                                Object... arguments)
                         throws UnsupportedTypeException,
                                ArityException,
                                UnknownIdentifierException,
                                UnsupportedMessageException

Sends an INVOKE Message to the foreign receiver object by executing the invokeNode .

Parameters:

invokeNode - the createNode created by Message.createNode()

receiver - foreign function object to receive the message passed to Message.createNode() method

arguments - arguments passed to the foreign function

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedTypeException - if one of element of the arguments has an unsupported type

UnknownIdentifierException - if the receiver does not have a property for the given identifier that can be invoked

ArityException - if the arguments array does not contain the right number of arguments for the foreign function

UnsupportedMessageException - if the receiver does not support the message represented by invokeNode

Since:

0.24

sendNew

public static Object sendNew(Node newNode,
                             TruffleObject receiver,
                             Object... arguments)
                      throws UnsupportedTypeException,
                             ArityException,
                             UnsupportedMessageException

Sends an NEW Message to the foreign receiver object by executing the newNode .

Parameters:

newNode - the createNode created by Message.createNode()

receiver - foreign function object to receive the message passed to Message.createNode() method

arguments - arguments passed to the foreign function

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedTypeException - if one of element of the arguments has an unsupported type

ArityException - if the arguments array does not contain the right number of arguments for the foreign function

UnsupportedMessageException - if the receiver does not support the message represented by newNode

Since:

0.24

sendIsNull

public static boolean sendIsNull(Node isNullNode,
                                 TruffleObject receiver)

Sends an IS_NULL message to the foreign receiver object by executing the isNullNode .

Parameters:

isNullNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.24

sendHasSize

public static boolean sendHasSize(Node hasSizeNode,
                                  TruffleObject receiver)

Sends an HAS_SIZE message to the foreign receiver object by executing the hasSizeNode .

Parameters:

hasSizeNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.24

sendGetSize

public static Object sendGetSize(Node getSizeNode,
                                 TruffleObject receiver)
                          throws UnsupportedMessageException

Sends a GET_SIZE message to the foreign receiver object by executing the getSizeNode .

Parameters:

getSizeNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

UnsupportedMessageException - if the receiver does not support the message represented by getSizeNode

Since:

0.24

sendIsBoxed

public static boolean sendIsBoxed(Node isBoxedNode,
                                  TruffleObject receiver)

Sends an IS_BOXED message to the foreign receiver object by executing the isNullNode .

Parameters:

isBoxedNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.24

sendKeyInfo

public static int sendKeyInfo(Node keyInfoNode,
                              TruffleObject receiver,
                              Object identifier)

Sends a KEY_INFO message to the foreign receiver object by executing the keyInfoNode. If the object does not support the message, the presence of the key is found by iteration over it's keys on a slow path and a default info is returned.

Parameters:

keyInfoNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

identifier - name of the property to get the info of.

Returns:

an integer value with bit flags described at KeyInfo.

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.26

sendHasKeys

public static boolean sendHasKeys(Node hasKeysNode,
                                  TruffleObject receiver)

Sends an HAS_KEYS message to the foreign receiver object by executing the hasKeysNode. If the object does not support the message, a Message.KEYS message is sent to test the presence of keys.

Parameters:

hasKeysNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return value, if any

Throws:

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.30

sendKeys

public static TruffleObject sendKeys(Node keysNode,
                                     TruffleObject receiver)
                              throws UnsupportedMessageException

Sends a Message.KEYS message to the foreign receiver object.

Parameters:

keysNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

Returns:

return an instance of TruffleObject that responds to Message.HAS_SIZE and Message.GET_SIZE and its 0 to size - 1 indexes contain String names of the properties of the receiver object

Throws:

UnsupportedMessageException - if the message isn't handled

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.24

sendKeys

public static TruffleObject sendKeys(Node keysNode,
                                     TruffleObject receiver,
                                     boolean includeInternal)
                              throws UnsupportedMessageException

Sends a Message.KEYS message to the foreign receiver object, with a specification of whether internal keys should be included in the result, or not.

Parameters:

keysNode - the createNode created by Message.createNode()

receiver - foreign object to receive the message passed to Message.createNode() method

includeInternal - true to include internal keys in the result, false to abandon them.

Returns:

return an instance of TruffleObject that responds to Message.HAS_SIZE and Message.GET_SIZE and its 0 to size - 1 indexes contain String names of the properties of the receiver object

Throws:

UnsupportedMessageException - if the message isn't handled

ClassCastException - if the createNode has not been created by Message.createNode() method.

Since:

0.26

getArguments

public static List<Object> getArguments(Frame frame)

Read only access to foreign call arguments inside of a frame.

Parameters:

frame - the frame that was called via ForeignAccess.send(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...)

Returns:

read-only list of parameters passed to the frame

Since:

0.11

getReceiver

public static TruffleObject getReceiver(Frame frame)

The foreign receiver in the frame.

Parameters:

frame - the frame that was called via ForeignAccess.send(com.oracle.truffle.api.nodes.Node, com.oracle.truffle.api.interop.TruffleObject, java.lang.Object...)

Returns:

the receiver used when invoking the frame

Since:

0.8 or earlier

toString

public String toString()

Overrides:

toString in class Object

Since:

0.8 or earlier