public abstract static class MutableTruffleString.FromNativePointerNode extends Node
MutableTruffleString
from an interop object representing a
native pointer. See MutableTruffleString.FromNativePointerNode.execute(Object, int, int, TruffleString.Encoding, boolean)
for
details.Node.Child, Node.Children
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 . |
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
public abstract MutableTruffleString execute(Object pointerObject, int byteOffset, int byteLength, TruffleString.Encoding encoding, boolean copy)
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.
TruffleLanguage.Env#isNativeAccessAllowed()
).public static MutableTruffleString.FromNativePointerNode create()
MutableTruffleString.FromNativePointerNode
.public static MutableTruffleString.FromNativePointerNode getUncached()
MutableTruffleString.FromNativePointerNode
.