com.oracle.truffle.api.interop

Class NodeLibrary

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.library.Library

com.oracle.truffle.api.interop.NodeLibrary

All Implemented Interfaces:

NodeInterface, Cloneable

public abstract class NodeLibrary
extends Library

Node Library provides access to guest language information associated with a particular Node location. The receiver of this library must be an instrumentable Node that has a root node.

Since:

20.3

Nested Class Summary

Nested classes/interfaces inherited from class com.oracle.truffle.api.nodes.Node

Node.Child, Node.Children

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	NodeLibrary()

Method Summary

Modifier and Type	Method and Description
static LibraryFactory<NodeLibrary>	getFactory() Returns the library factory for the node library.
Object	getReceiverMember(Object node, Frame frame) Returns an object that represents the receiver name when available.
Object	getRootInstance(Object node, Frame frame) Returns the current instance of guest language representation of the root node (e.g.
Object	getScope(Object node, Frame frame, boolean nodeEnter) Get an object representing a local scope containing variables visible at the node location.
static NodeLibrary	getUncached() Returns the uncached automatically dispatched version of the node library.
static NodeLibrary	getUncached(Object node) Returns the uncached manually dispatched version of the node library.
Object	getView(Object node, Frame frame, Object value) Wraps the value to filter or add scoping specific information for values associated with the current language and location in the code.
boolean	hasReceiverMember(Object node, Frame frame) Returns true, if there is a named receiver object, else false.
boolean	hasRootInstance(Object node, Frame frame) Returns true, if a current instance of the guest language representation of the root node (e.g.
boolean	hasScope(Object node, Frame frame) Returns true, if the node is in a scope containing local variables, else false.

Methods inherited from class com.oracle.truffle.api.library.Library

accepts

Methods inherited from class com.oracle.truffle.api.nodes.Node

accept, adoptChildren, atomic, atomic, copy, deepCopy, getChildren, getCost, getDebugProperties, getDescription, getEncapsulatingSourceSection, getLock, getParent, getRootNode, getSourceSection, insert, insert, isAdoptable, isSafelyReplaceableBy, notifyInserted, onReplace, replace, replace, reportPolymorphicSpecialize, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

NodeLibrary

protected NodeLibrary()

Since:

20.3

Method Detail

hasScope

public boolean hasScope(Object node,
                        Frame frame)

Returns true, if the node is in a scope containing local variables, else false.

This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.getScope(Object, Frame, boolean) must be implemented.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access.

Since:

20.3

See Also:

NodeLibrary.getScope(Object, Frame, boolean)

getScope

public Object getScope(Object node,
                       Frame frame,
                       boolean nodeEnter)
                throws UnsupportedMessageException

Get an object representing a local scope containing variables visible at the node location. The returned object must respond true to InteropLibrary.isScope(Object). The scope object exposes all locally visible variables as flattened members, including all parent scopes (for example block, closure, lexical or dynamic scopes). Local scopes are associated with a Frame. See InteropLibrary.isScope(Object) for details.

This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.hasScope(Object, Frame) must be implemented.

A returned scope is only valid while the regular guest language execution on this thread is suspended. If the guest execution is continued e.g. if a new instrumentation event occurs, the scope is invalid and should be discarded.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access.

nodeEnter - when true, the location that determines scope variables is at the enter to the node execution, else false. Use true when called e.g. by instruments from ExecutionEventNode.onEnter(VirtualFrame) and false when called e.g. from ExecutionEventNode.onReturnValue(VirtualFrame, Object). This argument helps to determine visible variables in case that some variables are added during the node execution.

Returns:

An interop object with InteropLibrary.isScope(Object) being true.

Throws:

UnsupportedMessageException - if and only if NodeLibrary.hasScope(Object, Frame) returns false for the same node and frame.

Since:

20.3

hasReceiverMember

public boolean hasReceiverMember(Object node,
                                 Frame frame)

Returns true, if there is a named receiver object, else false.

This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.getReceiverMember(Object, Frame) must be implemented.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access.

Since:

20.3

See Also:

NodeLibrary.getReceiverMember(Object, Frame)

getReceiverMember

public Object getReceiverMember(Object node,
                                Frame frame)
                         throws UnsupportedMessageException

Returns an object that represents the receiver name when available. The returned value is guaranteed to return true for InteropLibrary.isString(Object). Examples for receiver names are this in Java or self in Ruby or Python. The value of the receiver object can be retrieved from the scope by converting the member to a string using InteropLibrary.isString(Object). The return value of this method is an Object intentionally to allow the member to have additional interop traits.

This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.hasReceiverMember(Object, Frame) must be implemented.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access.

Returns:

an interop string object.

Throws:

UnsupportedMessageException - if and only if NodeLibrary.hasReceiverMember(Object, Frame) returns false for the same node and frame.

Since:

20.3

See Also:

NodeLibrary.hasReceiverMember(Object, Frame), NodeLibrary.getScope(Object, Frame, boolean)

hasRootInstance

public boolean hasRootInstance(Object node,
                               Frame frame)

Returns true, if a current instance of the guest language representation of the root node (e.g. the enclosing guest language function) is available, else false.

Guest languages will likely require a context lookup to resolve the root instance object. This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.getRootInstance(Object, Frame) must be implemented.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access, in which case the instance would likely not be available.

Since:

20.3

See Also:

NodeLibrary.getRootInstance(Object, Frame)

getRootInstance

public Object getRootInstance(Object node,
                              Frame frame)
                       throws UnsupportedMessageException

Returns the current instance of guest language representation of the root node (e.g. the enclosing guest language function), when available.

This method must not cause any observable side-effects. If this method is implemented then also NodeLibrary.hasRootInstance(Object, Frame) must be implemented.

Parameters:

node - a Node, never null

frame - a Frame, can be null in case of lexical access, in which case the instance would likely not be available.

Returns:

the root instance value which must be an interop and executable value.

Throws:

UnsupportedMessageException - if and only if NodeLibrary.hasRootInstance(Object, Frame) returns false for the same node and frame.

Since:

20.3

See Also:

NodeLibrary.hasRootInstance(Object, Frame)

getView

public Object getView(Object node,
                      Frame frame,
                      Object value)

Wraps the value to filter or add scoping specific information for values associated with the current language and location in the code. Allows the language to augment the perspective tools have on values depending on location and frame. This may be useful to apply local specific visibility rules. By default this method does return the passed value, not applying any scope information to the value. If a language does not implement any scoping and/or has not concept of visibility then this method typically can stay without an implementation. A typical implementation of this method may do the following:

• Apply visibility and scoping rules to the value hiding or removing members from the object.
• Add or remove implicit members that are only available within this source location.

This method is only invoked with values that are associated with the current language. For values without language the language view is requested first before the scoped view is requested. If this method needs an implementation then TruffleLanguage.getLanguageView(Object, Object) should be implemented as well.

Scoped views may be implemented in a very similar way to language views. Please refer to the examples from this method.

Parameters:

node - the current source location. Guaranteed to be a node from a RootNode associated with this language. Never null.

frame - the current active frame. Guaranteed to be a frame from a RootNode associated with this language. Never null.

value - the value to provide scope information for. Never null. Always associated with this language.

Since:

20.3

See Also:

TruffleLanguage.getLanguageView(Object, Object)

getFactory

public static LibraryFactory<NodeLibrary> getFactory()

Returns the library factory for the node library. Short-cut for ResolvedLibrary.resolve(NodeLibrary.class).

Since:

20.3

See Also:

LibraryFactory.resolve(Class)

getUncached

public static NodeLibrary getUncached()

Returns the uncached automatically dispatched version of the node library. This is a short-cut for calling NodeLibrary.getFactory().getUncached().

Since:

20.3

See Also:

LibraryFactory.getUncached()

getUncached

public static NodeLibrary getUncached(Object node)

Returns the uncached manually dispatched version of the node library. This is a short-cut for calling NodeLibrary.getFactory().getUncached(v).

Since:

20.3

See Also:

LibraryFactory.getUncached(Object)