com.oracle.truffle.api.strings

Class TruffleString.FromNativePointerNode

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.strings.TruffleString.FromNativePointerNode

All Implemented Interfaces:

NodeInterface, Cloneable

Enclosing class:

TruffleString

public abstract static class TruffleString.FromNativePointerNode
extends Node

Node to create a new TruffleString from an interop object representing a native pointer. See TruffleString.FromNativePointerNode.execute(Object, int, int, TruffleString.Encoding, boolean) for details.

Since:

22.1

Nested Class Summary

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

Node.Child, Node.Children

Method Summary

Modifier and Type	Method and Description
static TruffleString.FromNativePointerNode	create() Create a new TruffleString.FromNativePointerNode.
abstract TruffleString	execute(Object pointerObject, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy) Create a new TruffleString from an interop object representing a native pointer ( isPointer(pointerObject) must return true).
static TruffleString.FromNativePointerNode	getUncached() Get the uncached version of TruffleString.FromNativePointerNode.

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

Method Detail

execute

public abstract TruffleString execute(Object pointerObject,
                                      int byteOffset,
                                      int byteLength,
                                      TruffleString.Encoding encoding,
                                      boolean copy)

Create a new TruffleString from an interop object representing a native pointer ( isPointer(pointerObject) must return true). The pointer is immediately unboxed with (asPointer(pointerObject)) and saved in the TruffleString instance, i.e. TruffleString assumes that the pointer address does not change. The pointer's content is assumed to be encoded in the given encoding already. If copy is false, the native pointer is used directly as the new string's backing storage. Caution: TruffleString assumes the pointer's content to be immutable, do not modify the pointer's content after passing it to this operation!

WARNING: TruffleString cannot reason about the lifetime of the native pointer, so it is up to the user to make sure that the native pointer is valid to access and not freed as long the pointerObject is alive (if copy is false). To help with this the TruffleString keeps a reference to the given pointerObject, so the pointerObject is kept alive at least as long as the TruffleString is used. In order to be able to use the string past the native pointer's life time, convert it to a managed string via TruffleString.AsManagedNode before the native pointer is freed.

If copy is true, the pointer's contents are copied to a Java byte array, and the pointer can be freed safely after the operation completes.

This operation requires native access permissions (TruffleLanguage.Env#isNativeAccessAllowed()).

Since:

22.1

create

public static TruffleString.FromNativePointerNode create()

Create a new TruffleString.FromNativePointerNode.

Since:

22.1

getUncached

public static TruffleString.FromNativePointerNode getUncached()

Get the uncached version of TruffleString.FromNativePointerNode.

Since:

22.1