Class MutableTruffleString.FromNativePointerNode

java.lang.Object

com.oracle.truffle.api.nodes.Node

com.oracle.truffle.api.strings.MutableTruffleString.FromNativePointerNode

All Implemented Interfaces:

NodeInterface, Cloneable

Enclosing class:

MutableTruffleString

public abstract static class MutableTruffleString.FromNativePointerNode
extends Node

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

Since:

22.1

Nested Class Summary

Nested classes/interfaces inherited from class Node

Node.Child, Node.Children

Method Summary

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

Methods inherited from class 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, reportReplace, toString

Methods inherited from class Object

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

Method Details

execute

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

Create a new MutableTruffleString from an interop object representing a native pointer (isPointer(pointerObject) must return true). The pointer is immediately unboxed with (asPointer(pointerObject)) and saved until the end of the string's lifetime, i.e. MutableTruffleString 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: If the pointer's content is modified after string creation, the string must be notified of this via MutableTruffleString.notifyExternalMutation().

WARNING: MutableTruffleString 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 MutableTruffleString keeps a reference to the given pointerObject, so the pointerObject is kept alive at least as long as the MutableTruffleString 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 MutableTruffleString.AsManagedNode before the native pointer is freed.

Since GraalVM version 25.1, the native pointer may also be passed as a boxed long value in place of pointerObject. Note that in this case, the resulting MutableTruffleString cannot keep a reference an associated object for life-time tracking. The user is responsible for making sure the native buffer is not freed as long as the MutableTruffleString object is alive.

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 MutableTruffleString.FromNativePointerNode create()

Create a new MutableTruffleString.FromNativePointerNode.

Since:

22.1

getUncached

public static MutableTruffleString.FromNativePointerNode getUncached()

Get the uncached version of MutableTruffleString.FromNativePointerNode.

Since:

22.1