8352861: Template-Framework Library

test/hotspot/jtreg/compiler/lib/template_framework/AddNameToken.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+record AddNameToken(Name name) implements Token {}

test/hotspot/jtreg/compiler/lib/template_framework/Code.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * This class collects code, i.e. {@link String}s or {@link List}s of {@link String}s.
+ * All the Strings are later collected in a {@link StringBuilder}. If we used a {@link StringBuilder}
+ * directly to collect the Strings, we could not as easily insert code at an "earlier" position, i.e.
+ * reaching out to a {@link Hook#set}.
+ */
+sealed interface Code permits Code.Token, Code.CodeList {
+
+    record Token(String s) implements Code {
+        @Override
+        public void renderTo(StringBuilder builder) {
+            builder.append(s);
+        }
+    }
+
+    record CodeList(List<Code> list) implements Code {
+        @Override
+        public void renderTo(StringBuilder builder) {
+            list.forEach(code -> code.renderTo(builder));
+        }
+    }
+
+    void renderTo(StringBuilder builder);
+}

test/hotspot/jtreg/compiler/lib/template_framework/CodeFrame.java

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * The {@link CodeFrame} represents a frame (i.e. scope) of code, appending {@link Code} to the {@code 'codeList'}
+ * as {@link Token}s are rendered, and adding names to the {@link NameSet}s as they get defined by {@link Template#define}.
+ * {@link Hook}s can be added to a frame, which allows code to be inserted at that location later.
+ * When a {@link Hook} is {@link Hook#set}, this separates the {@link Template} into an outer and inner
+ * {@link CodeFrame}, ensuring that names that are {@link Template#defineName}'d inside the inner frame
+ * are only available inside that frame.
+ *
+ * <p>
+ * On the other hand, each {@link TemplateFrame} represents the frame (or scope) of exactly one use of a
+ * {@link Template}.
+ *
+ * <p>
+ * For simple {@link Template} nesting, the {@link CodeFrame}s and {@link TemplateFrame}s overlap exactly.
+ * However, when using {@link Hook#insert}, we simply nest {@link TemplateFrame}s, going further "in",
+ * but we jump to an outer {@link CodeFrame}, ensuring that we insert {@link Code} at the outer frame,
+ * and operating on the names of the outer frame. Once the {@link Hook#insert}ion is complete, we jump
+ * back to the caller {@link TemplateFrame} and {@link CodeFrame}.
+ */
+class CodeFrame {
+    public final CodeFrame parent;
+    private final List<Code> codeList = new ArrayList<Code>();
+    private final Map<Hook, Code.CodeList> hookCodeLists = new HashMap<>();
+
+    /**
+     * The {@link NameSet} is used for variable and fields etc.
+     */
+    final NameSet names;
+
+    private CodeFrame(CodeFrame parent, boolean isTransparentForNames) {
+        this.parent = parent;
+        if (parent == null) {
+            // NameSet without any parent.
+            this.names = new NameSet(null);
+        } else if (isTransparentForNames) {
+            // We use the same NameSet as the parent - makes it transparent.
+            this.names     = parent.names;
+        } else {
+            // New NameSet, to make sure we have a nested scope for the names.
+            this.names     = new NameSet(parent.names);
+        }
+    }
+
+    /**
+     * Creates a base frame, which has no {@link parent}.
+     */
+    public static CodeFrame makeBase() {
+        return new CodeFrame(null, false);
+    }
+
+    /**
+     * Creates a normal frame, which has a {@link parent} and which defines an inner
+     * {@link NameSet}, for the names that are generated inside this frame. Once this
+     * frame is exited, the name from inside this frame are not available any more.
+     */
+    public static CodeFrame make(CodeFrame parent) {
+        return new CodeFrame(parent, false);
+    }
+
+    /**
+     * Creates a special frame, which has a {@link parent} and but uses the {@link NameSet}
+     * from the parent frame, allowing {@link Template#defineName} to persist in the outer
+     * frame when the current frame is exited. This is necessary for {@link Hook#insert},
+     * where we would possibly want to make field or variable definitions during the insertion
+     * that are not just local to the insertion but affect the {@link CodeFrame} that we
+     * {@link Hook#set} earlier and are now {@link Hook#insert}ing into.
+     */
+    public static CodeFrame makeTransparentForNames(CodeFrame parent) {
+        return new CodeFrame(parent, true);
+    }
+
+    void addString(String s) {
+        codeList.add(new Code.Token(s));
+    }
+
+    void addCode(Code code) {
+        codeList.add(code);
+    }
+
+    void addHook(Hook hook) {
+        if (hasHook(hook)) {
+            // This should never happen, as we add a dedicated CodeFrame for each hook.
+            throw new RuntimeException("Internal error: Duplicate Hook in CodeFrame: " + hook.name());
+        }
+        hookCodeLists.put(hook, new Code.CodeList(new ArrayList<Code>()));
+    }
+
+    boolean hasHook(Hook hook) {
+        return hookCodeLists.containsKey(hook);
+    }
+
+    CodeFrame codeFrameForHook(Hook hook) {
+        CodeFrame current = this;
+        while (current != null) {
+            if (current.hasHook(hook)) {
+                return current;
+            }
+            current = current.parent;
+        }
+        return null;
+    }
+
+    void addName(Name name) {
+        names.add(name);
+    }
+
+    long weighNames(Name.Type type, boolean onlyMutable) {
+        return names.weight(type, onlyMutable);
+    }
+
+    Name sampleName(Name.Type type, boolean onlyMutable) {
+        return names.sample(type, onlyMutable);
+    }
+
+    Code getCode() {
+        return new Code.CodeList(codeList);
+    }
+}

test/hotspot/jtreg/compiler/lib/template_framework/Hook.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+import java.util.List;
+
+/**
+ * {@link Hook}s can be {@link set} for a certain scope in a {@link Template}, and all nested
+ * {@link Template}s in this scope, and then from within this scope, any {@link Template} can
+ * {@link insert} code to where the {@link Hook} was {@link set}. This can be useful to reach
+ * "back" or to some outer scope, e.g. while generating code for a method, one can reach out
+ * to the class scope to insert fields.
+ *
+ * Example:
+ * {@snippet lang=java :
+ * var myHook = new Hook("MyHook");
+ *
+ * var template1 = Template.make("name", (String name) -> body(
+ *     """
+ *     public static int #name = 42;
+ *     """
+ * ));
+ *
+ * var template2 = Template.make(() -> body(
+ *     """
+ *     public class Test {
+ *     """,
+ *     // Set the hook here.
+ *     myHook.set(
+ *         """
+ *         public static void main(String[] args) {
+ *         System.out.println("$field: " + $field)
+ *         """,
+ *         // Reach out to where the hook was set, and insert the code of template1.
+ *         myHook.insert(template1.withArgs($("field"))),
+ *         """
+ *         }
+ *         """
+ *     ),
+ *     """
+ *     }
+ *     """
+ * ));
+ * }
+ *
+ * @param name The name of the Hook, for debugging purposes only.
+ */
+public record Hook(String name) {
+    /**
+     * Set this {@link Hook} for the scope of the provided {@code 'tokens'}.
+     * From anywhere inside this scope, even in nested {@link Template}s, code can be
+     * {@link insert}ed back to the location where this {@link Hook} was {@link set}.
+     *
+     * @param tokens A list of tokens, which have the same restrictions as {@link Template#body}.
+     * @return A {@link Token} that captures the setting of the scope and the list of validated {@link Token}s.
+     */
+    public Token set(Object... tokens) {
+        return new HookSetToken(this, Token.parse(tokens));
+    }
+
+    /**
+     * Inserts a {@link TemplateWithArgs} to the innermost location where this {@link Hook} was {@link set}.
+     * This could be in the same {@link Template}, or one nested further out.
+     *
+     * @param templateWithArgs The {@link Template} with applied arguments to be inserted at the {@link Hook}.
+     * @return The {@link Token} which when used inside a {@link Template#body} performs the code insertion into the {@link Hook}.
+     */
+    public Token insert(TemplateWithArgs templateWithArgs) {
+        return new HookInsertToken(this, templateWithArgs);
+    }
+
+    /**
+     * Checks if the {@link Hook} was {@link Hook#set} for the current scope or an outer scope.
+     *
+     * @return If the {@link Hook} was {@link Hook#set} for the current scope or an outer scope.
+     */
+    public boolean isSet() {
+        return Renderer.getCurrent().isSet(this);
+    }
+}

test/hotspot/jtreg/compiler/lib/template_framework/HookInsertToken.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+record HookInsertToken(Hook hook, TemplateWithArgs templateWithArgs) implements Token {}

test/hotspot/jtreg/compiler/lib/template_framework/HookSetToken.java

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package compiler.lib.template_framework;
+
+import java.util.List;
+
+record HookSetToken(Hook hook, List<Token> tokens) implements Token {}