com.oracle.truffle.api.strings

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 MutableTruffleString.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 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 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 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.

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