TruffleString: add MaterializeSubstringNode.

Author: djoooooe

truffle/CHANGELOG.md

@@ -17,6 +17,8 @@ This changelog summarizes major changes between Truffle versions relevant to lan
 * GR-67146: Bytecode DSL: Added support for user-defined yield operations using `@Yield`. These operations behave like the built-in yield but allow you to customize the yield result or perform custom logic on yield.
 * GR-69495: Bytecode DSL: Added a new `storeBytecodeIndex` attribute to all operation annotations to configure whether the bytecode index needs to be stored. When `@GenerateBytecode(storeBytecodeIndexInFrame = true)` is set and the attribute is left at its default, the DSL will emit a warning recommending explicit configuration. Additionally, introduced the `@StoreBytecodeIndex` annotation, which lets you specify bytecode index updates for individual specializations or fallbacks.
 
+* GR-68916: Added `TruffleString.MaterializeLazySubstringNode`. Use this node to free any unnecessary memory held by lazy substrings.
+* GR-68916: Added `TruffleString.MaterializeSubstringNode`. Use this node to free any unnecessary memory held by lazy substrings.
 
 ## Version 25.0
 * GR-31495 Added ability to specify language and instrument specific options using `Source.Builder.option(String, String)`. Languages may describe available source options by implementing `TruffleLanguage.getSourceOptionDescriptors()` and `TruffleInstrument.getSourceOptionDescriptors()` respectively.

truffle/src/com.oracle.truffle.api.strings.test/src/com/oracle/truffle/api/strings/test/ops/TStringMaterializeLazySubstringTest.java

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.oracle.truffle.api.strings.test.ops;
+
+import static org.junit.runners.Parameterized.Parameter;
+import static org.junit.runners.Parameterized.Parameters;
+
+import java.util.Arrays;
+
+import org.junit.Assert;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.Parameterized;
+
+import com.oracle.truffle.api.strings.InternalByteArray;
+import com.oracle.truffle.api.strings.TruffleString;
+import com.oracle.truffle.api.strings.test.TStringTestBase;
+
+@RunWith(Parameterized.class)
+public class TStringMaterializeLazySubstringTest extends TStringTestBase {
+
+    @Parameter public TruffleString.MaterializeSubstringNode node;
+
+    @Parameters(name = "{0}")
+    public static Iterable<TruffleString.MaterializeSubstringNode> data() {
+        return Arrays.asList(TruffleString.MaterializeSubstringNode.create(), TruffleString.MaterializeSubstringNode.getUncached());
+    }
+
+    @Test
+    public void testAll() throws Exception {
+        forAllStrings(true, (a, array, codeRange, isValid, encoding, codepoints, byteIndices) -> {
+            TruffleString b = node.execute(a, encoding);
+            assertBytesEqual(b, encoding, array);
+            assertCodePointsEqual(b, encoding, codepoints);
+            InternalByteArray internalByteArray = b.getInternalByteArrayUncached(encoding);
+            Assert.assertEquals(0, internalByteArray.getOffset());
+            Assert.assertEquals(array.length, internalByteArray.getLength());
+        });
+    }
+
+    @Test
+    public void testNull() throws Exception {
+        checkNullSE((s, e) -> node.execute(s, e));
+    }
+}

truffle/src/com.oracle.truffle.api.strings/snapshot.sigtest

@@ -81,6 +81,7 @@ hfds GIL_LOCK,PARENT_LIMIT,SAME_LANGUAGE_CHECK_VISITOR,parent
 CLSS public abstract interface com.oracle.truffle.api.nodes.NodeInterface
 
 CLSS public abstract com.oracle.truffle.api.strings.AbstractTruffleString
+meth public com.oracle.truffle.api.strings.TruffleString materializeSubstringUncached(com.oracle.truffle.api.strings.TruffleString$Encoding)
 meth public com.oracle.truffle.api.strings.TruffleString toValidStringUncached(com.oracle.truffle.api.strings.TruffleString$Encoding)
 meth public final boolean codeRangeEqualsUncached(com.oracle.truffle.api.strings.TruffleString$CodeRange)
 meth public final boolean equals(java.lang.Object)
@@ -163,6 +164,8 @@ meth public final void copyToNativeMemoryNodeUncached(int,java.lang.Object,int,i
  anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="22.3")
 meth public final void copyToNativeMemoryUncached(int,java.lang.Object,int,int,com.oracle.truffle.api.strings.TruffleString$Encoding)
 meth public void materializeUncached(com.oracle.truffle.api.strings.AbstractTruffleString,com.oracle.truffle.api.strings.TruffleString$Encoding)
+ anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="26.0")
+meth public void materializeUncached(com.oracle.truffle.api.strings.TruffleString$Encoding)
 supr java.lang.Object
 hfds DEBUG_ALWAYS_CREATE_JAVA_STRING,DEBUG_NON_ZERO_OFFSET,DEBUG_STRICT_ENCODING_CHECKS,MASKED_ZERO_HASH_CODE,codePointLength,codeRange,data,encoding,flags,hashCode,length,offset,stride
 hcls LazyConcat,LazyLong,NativePointer
@@ -343,6 +346,7 @@ innr public abstract static LastByteIndexOfStringNode
 innr public abstract static LastIndexOfCodePointNode
 innr public abstract static LastIndexOfStringNode
 innr public abstract static MaterializeNode
+innr public abstract static MaterializeSubstringNode
 innr public abstract static ParseDoubleNode
 innr public abstract static ParseIntNode
 innr public abstract static ParseLongNode
@@ -895,6 +899,13 @@ meth public static com.oracle.truffle.api.strings.TruffleString$MaterializeNode
 meth public static com.oracle.truffle.api.strings.TruffleString$MaterializeNode getUncached()
 supr com.oracle.truffle.api.nodes.Node
 
+CLSS public abstract static com.oracle.truffle.api.strings.TruffleString$MaterializeSubstringNode
+ outer com.oracle.truffle.api.strings.TruffleString
+meth public abstract com.oracle.truffle.api.strings.TruffleString execute(com.oracle.truffle.api.strings.AbstractTruffleString,com.oracle.truffle.api.strings.TruffleString$Encoding)
+meth public static com.oracle.truffle.api.strings.TruffleString$MaterializeSubstringNode create()
+meth public static com.oracle.truffle.api.strings.TruffleString$MaterializeSubstringNode getUncached()
+supr com.oracle.truffle.api.nodes.Node
+
 CLSS public final static com.oracle.truffle.api.strings.TruffleString$NumberFormatException
  outer com.oracle.truffle.api.strings.TruffleString
 meth public java.lang.String getMessage()
@@ -1150,7 +1161,7 @@ CLSS public final com.oracle.truffle.api.strings.TruffleStringFactory
 cons public init()
 innr public final static WithMaskFactory
 supr java.lang.Object
-hcls AsManagedNodeGen,AsNativeNodeGen,AsTruffleStringNodeGen,ByteIndexOfAnyByteNodeGen,ByteIndexOfCodePointNodeGen,ByteIndexOfCodePointSetNodeGen,ByteIndexOfStringNodeGen,ByteIndexToCodePointIndexNodeGen,ByteLengthOfCodePointNodeGen,CharIndexOfAnyCharUTF16NodeGen,CodePointAtByteIndexNodeGen,CodePointAtIndexNodeGen,CodePointIndexToByteIndexNodeGen,CodePointLengthNodeGen,CodeRangeEqualsNodeGen,CompareBytesNodeGen,CompareCharsUTF16NodeGen,CompareIntsUTF32NodeGen,ConcatNodeGen,CopyToByteArrayNodeGen,CopyToNativeMemoryNodeGen,CreateBackwardCodePointIteratorNodeGen,CreateCodePointIteratorNodeGen,EqualNodeGen,ForceEncodingNodeGen,FromByteArrayNodeGen,FromCharArrayUTF16NodeGen,FromCodePointNodeGen,FromIntArrayUTF32NodeGen,FromJavaStringNodeGen,FromLongNodeGen,FromNativePointerNodeGen,GetByteCodeRangeNodeGen,GetCodeRangeImpreciseNodeGen,GetCodeRangeNodeGen,GetInternalByteArrayNodeGen,GetInternalNativePointerNodeGen,GetStringCompactionLevelNodeGen,HashCodeNodeGen,IndexOfCodePointNodeGen,IndexOfStringNodeGen,IntIndexOfAnyIntUTF32NodeGen,InternalAsTruffleStringNodeGen,InternalCopyToByteArrayNodeGen,InternalSwitchEncodingNodeGen,IsValidNodeGen,LastByteIndexOfCodePointNodeGen,LastByteIndexOfStringNodeGen,LastIndexOfCodePointNodeGen,LastIndexOfStringNodeGen,MaterializeNodeGen,ParseDoubleNodeGen,ParseIntNodeGen,ParseLongNodeGen,ReadByteNodeGen,ReadCharUTF16NodeGen,RegionEqualByteIndexNodeGen,RegionEqualNodeGen,RepeatNodeGen,SubstringByteIndexNodeGen,SubstringNodeGen,SwitchEncodingNodeGen,ToJavaStringNodeGen,ToValidStringNodeGen
+hcls AsManagedNodeGen,AsNativeNodeGen,AsTruffleStringNodeGen,ByteIndexOfAnyByteNodeGen,ByteIndexOfCodePointNodeGen,ByteIndexOfCodePointSetNodeGen,ByteIndexOfStringNodeGen,ByteIndexToCodePointIndexNodeGen,ByteLengthOfCodePointNodeGen,CharIndexOfAnyCharUTF16NodeGen,CodePointAtByteIndexNodeGen,CodePointAtIndexNodeGen,CodePointIndexToByteIndexNodeGen,CodePointLengthNodeGen,CodeRangeEqualsNodeGen,CompareBytesNodeGen,CompareCharsUTF16NodeGen,CompareIntsUTF32NodeGen,ConcatNodeGen,CopyToByteArrayNodeGen,CopyToNativeMemoryNodeGen,CreateBackwardCodePointIteratorNodeGen,CreateCodePointIteratorNodeGen,EqualNodeGen,ForceEncodingNodeGen,FromByteArrayNodeGen,FromCharArrayUTF16NodeGen,FromCodePointNodeGen,FromIntArrayUTF32NodeGen,FromJavaStringNodeGen,FromLongNodeGen,FromNativePointerNodeGen,GetByteCodeRangeNodeGen,GetCodeRangeImpreciseNodeGen,GetCodeRangeNodeGen,GetInternalByteArrayNodeGen,GetInternalNativePointerNodeGen,GetStringCompactionLevelNodeGen,HashCodeNodeGen,IndexOfCodePointNodeGen,IndexOfStringNodeGen,IntIndexOfAnyIntUTF32NodeGen,InternalAsTruffleStringNodeGen,InternalCopyToByteArrayNodeGen,InternalSwitchEncodingNodeGen,IsValidNodeGen,LastByteIndexOfCodePointNodeGen,LastByteIndexOfStringNodeGen,LastIndexOfCodePointNodeGen,LastIndexOfStringNodeGen,MaterializeNodeGen,MaterializeSubstringNodeGen,ParseDoubleNodeGen,ParseIntNodeGen,ParseLongNodeGen,ReadByteNodeGen,ReadCharUTF16NodeGen,RegionEqualByteIndexNodeGen,RegionEqualNodeGen,RepeatNodeGen,SubstringByteIndexNodeGen,SubstringNodeGen,SwitchEncodingNodeGen,ToJavaStringNodeGen,ToValidStringNodeGen
 
 CLSS public final static com.oracle.truffle.api.strings.TruffleStringFactory$WithMaskFactory
  outer com.oracle.truffle.api.strings.TruffleStringFactory

truffle/src/com.oracle.truffle.api.strings/src/com/oracle/truffle/api/strings/AbstractTruffleString.java

@@ -628,13 +628,35 @@ public final MutableTruffleString asManagedMutableTruffleStringUncached(TruffleS
     /**
      * Shorthand for calling the uncached version of {@link TruffleString.MaterializeNode}.
      *
+     * @deprecated since 26.0, use {@link #materializeUncached(Encoding)} instead.
      * @since 23.1
      */
+    @Deprecated(since = "26.0")
     @TruffleBoundary
     public void materializeUncached(AbstractTruffleString a, Encoding expectedEncoding) {
         TruffleString.MaterializeNode.getUncached().execute(a, expectedEncoding);
     }
 
+    /**
+     * Shorthand for calling the uncached version of {@link TruffleString.MaterializeNode}.
+     *
+     * @since 26.0
+     */
+    @TruffleBoundary
+    public void materializeUncached(Encoding expectedEncoding) {
+        TruffleString.MaterializeNode.getUncached().execute(this, expectedEncoding);
+    }
+
+    /**
+     * Shorthand for calling the uncached version of {@link TruffleString.MaterializeSubstringNode}.
+     *
+     * @since 26.0
+     */
+    @TruffleBoundary
+    public TruffleString materializeSubstringUncached(Encoding expectedEncoding) {
+        return TruffleString.MaterializeSubstringNode.getUncached().execute(this, expectedEncoding);
+    }
+
     /**
      * Shorthand for calling the uncached version of {@link TruffleString.GetCodeRangeNode}.
      *

truffle/src/com.oracle.truffle.api.strings/src/com/oracle/truffle/api/strings/TruffleString.java

@@ -2591,6 +2591,103 @@ public static MaterializeNode getUncached() {
         }
     }
 
+    /**
+     * Extended version of {@link MaterializeNode} that also materializes substrings/string views
+     * created via e.g. {@link SubstringNode} with the {@code lazy} parameter set to {@code true} or
+     * via {@link FromByteArrayNode} with the {@code copy} parameter set to {@code false}. Note that
+     * this node returns a potentially new {@link TruffleString}, because these substrings cannot be
+     * materialized internally. {@link #isNative() Native-backed} strings are kept as-is, since this
+     * node cannot decide whether a native-backed string is a substring/string view.
+     * <p>
+     * Lazy substrings keep a reference to the potentially larger byte array they were created from,
+     * which may keep more memory alive than necessary (see the caveats mentioned at
+     * {@link SubstringNode#execute}). With this node, unnecessarily held memory is reclaimed by
+     * copying the referenced subregions. This is especially useful if a string is added to a data
+     * structure known to be long-lived, e.g. during string interning.
+     *
+     * @see SubstringNode#execute
+     * @since 26.0
+     */
+    public abstract static class MaterializeSubstringNode extends AbstractPublicNode {
+
+        MaterializeSubstringNode() {
+        }
+
+        /**
+         * Extended version of {@link MaterializeNode} that also materializes substrings/string
+         * views created via e.g. {@link SubstringNode} with the {@code lazy} parameter set to
+         * {@code true} or via {@link FromByteArrayNode} with the {@code copy} parameter set to
+         * {@code false}. Note that this node returns a potentially new {@link TruffleString},
+         * because these substrings cannot be materialized internally. {@link #isNative()
+         * Native-backed} strings are kept as-is, since this node cannot decide whether a
+         * native-backed string is a substring/string view.
+         * <p>
+         * Lazy substrings keep a reference to the potentially larger byte array they were created
+         * from, which may keep more memory alive than necessary (see the caveats mentioned at
+         * {@link SubstringNode#execute}). With this node, unnecessarily held memory is reclaimed by
+         * copying the referenced subregions. This is especially useful if a string is added to a
+         * data structure known to be long-lived, e.g. during string interning.
+         *
+         * @see SubstringNode#execute
+         * @since 26.0
+         */
+        public abstract TruffleString execute(AbstractTruffleString a, Encoding expectedEncoding);
+
+        @Specialization
+        final TruffleString doTruffleString(TruffleString a, Encoding expectedEncoding,
+                        @Cached InlinedConditionProfile managedProfileA,
+                        @Cached InlinedConditionProfile nativeProfileA,
+                        @Cached InlinedConditionProfile stringViewProfile) {
+            a.checkEncoding(expectedEncoding);
+            Object dataA = a.data();
+            try {
+                if (managedProfileA.profile(this, dataA instanceof byte[])) {
+                    final byte[] arrayA = (byte[]) dataA;
+                    int byteLength = a.length() << a.stride();
+                    if (stringViewProfile.profile(this, byteLength < arrayA.length)) {
+                        byte[] copy = new byte[byteLength];
+                        System.arraycopy(arrayA, a.offset(), copy, 0, byteLength);
+                        return TruffleString.createFromByteArray(copy, 0, a.length(), a.stride(), expectedEncoding, a.codePointLength(), a.codeRange(), a.hashCode, true);
+                    } else {
+                        return a;
+                    }
+                } else if (nativeProfileA.profile(this, dataA instanceof NativePointer)) {
+                    return a;
+                } else {
+                    a.materializeLazy(this, dataA);
+                    return a;
+                }
+            } finally {
+                Reference.reachabilityFence(dataA);
+            }
+        }
+
+        @Specialization
+        final TruffleString doMutableTruffleString(MutableTruffleString a, Encoding expectedEncoding,
+                        @Cached TStringInternalNodes.FromBufferWithStringCompactionKnownAttributesNode fromBufferWithStringCompactionNode) {
+            return fromBufferWithStringCompactionNode.execute(this, a, expectedEncoding);
+        }
+
+        /**
+         * Create a new {@link MaterializeSubstringNode}.
+         *
+         * @since 26.0
+         */
+        @NeverDefault
+        public static MaterializeSubstringNode create() {
+            return TruffleStringFactory.MaterializeSubstringNodeGen.create();
+        }
+
+        /**
+         * Get the uncached version of {@link MaterializeSubstringNode}.
+         *
+         * @since 26.0
+         */
+        public static MaterializeSubstringNode getUncached() {
+            return TruffleStringFactory.MaterializeSubstringNodeGen.getUncached();
+        }
+    }
+
     /**
      * Node to get a string's precise {@link CodeRange}.
      *