8344942: Template-Based Testing Framework

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

@@ -0,0 +1,54 @@
+/*
+ * 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;
+
+/**
+ * {link BaseScope} is the outer-most scope, and determines the {@link CodeGeneratorLibrary} which is used.
+ */
+final class BaseScope extends Scope {
+    public static final int DEFAULT_FUEL = 50;
+    private final CodeGeneratorLibrary codeGeneratorLibrary;
+
+    public BaseScope(long fuel, CodeGeneratorLibrary codeGeneratorLibrary) {
+        super(null, fuel);
+        this.codeGeneratorLibrary = (codeGeneratorLibrary != null) ? codeGeneratorLibrary
+                                                                   : CodeGeneratorLibrary.standard();
+    }
+
+    public BaseScope(CodeGeneratorLibrary codeGeneratorLibrary) {
+        this(DEFAULT_FUEL, codeGeneratorLibrary);
+    };
+
+    @Override
+    public CodeGeneratorLibrary library() {
+        return codeGeneratorLibrary;
+    }
+
+    /**
+     * Collect all the generated code and return it as a String.
+     */
+    public String toString() {
+        return stream.toString();
+    }
+}

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

@@ -0,0 +1,43 @@
+/*
+ * 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;
+
+/**
+ * The {@link ClassScope} sets the scope of a class body, i.e. after its opening bracked and before its
+ * closing bracket. This allows dispatching {@link CodeGenerator}s to the top of the class body, for
+ * example for field declarations, see {@link DispatchScope#dispatch}. In {@link Template}s, a
+ * {@link ClassScope} is opened with {@code #open(class)} and closed with {@code #close(class)}.
+ */
+final class ClassScope extends DispatchScope {
+
+    /**
+     * Create a new {@link MethodScope}.
+     *
+     * @param parent Parent scope or null if the new scope is an outermost scope.
+     * @param fuel Remaining fuel for recursive {@link CodeGenerator} instantiations.
+     */
+    public ClassScope(Scope parent, long fuel) {
+        super(parent, fuel);
+    }
+}

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

@@ -0,0 +1,209 @@
+/*
+ * 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.Map;
+
+/**
+ * A {@link CodeGenerator} is used to instantiate code into a scope. This instantiated code may be genrated recursively
+ * i.e. the {@link CodeGenerator} instantiation may recursively instantiate other {@link CodeGenerator}s.
+ */
+public sealed abstract class CodeGenerator permits Template, ProgrammaticCodeGenerator, SelectorCodeGenerator {
+
+    /**
+     * Every {@link CodeGenerator} must have an unique name. The name is used to find {@link CodeGenerator}s in the
+     * {@link CodeGeneratorLibrary}, and also in the {@link Scope} trace printed if the Template Framework encounters
+     * an error.
+     */
+    public final String name;
+
+
+    /**
+     * The fuel cost indicates the approximate logarithmic execution cost of the code generated by the
+     * {@link CodeGenerator}. When CodeGenerators are called recursively, the fuel cost is subtracted from the
+     * remaining fuel of the {@link Scope}. Once the scope runs out of fuel, the recursion is supposed to stop.
+     */
+    public final int fuelCost;
+
+    /**
+     * Create a new {@link CodeGenerator}.
+     *
+     * @param name Name of the generator, can be used for lookup in the
+     *             {@link CodeGeneratorLibrary} if the {@link Template}
+     *             is added to a library.
+     * @param fuelCost The {@link fuelCost} for the {@link CodeGenerator}.
+     */
+    CodeGenerator(String name, int fuelCost) {
+        this.name = name;
+        this.fuelCost = fuelCost;
+    }
+
+    /**
+     * Instantiate the CodeGenerator.
+     *
+     * @param scope Scope into which the code is generated.
+     * @param parameters Provides the parameters for the instantiation, as well as a unique ID for identifier
+     *                   name generation (e.g. variable of method names).
+     */
+    public abstract void instantiate(Scope scope, Parameters parameters);
+
+    /**
+     * Helper facility to instantiate CodeGenerators more easily. It creates a unique Parameter set which can
+     * be further populated with {@link where}.
+     */
+    public final class Instantiator {
+        private final CodeGenerator codeGenerator;
+        private final Parameters parameters;
+        private boolean isUsed;
+        private CodeGeneratorLibrary library;
+
+	Instantiator(CodeGenerator codeGenerator) {
+            this.codeGenerator = codeGenerator;
+            this.parameters = new Parameters();
+            this.library = null;
+        }
+
+        /**
+         * Add a parameter key-value pair.
+         *
+         * @param paramKey The name of the parameter.
+         * @param paramValue The value to be set.
+         * @return The Instantiator for chaining.
+         */
+        public Instantiator where(String paramKey, String paramValue) {
+            parameters.add(paramKey, paramValue);
+            return this;
+        }
+
+        /**
+         * Add all parameter key-value pairs.
+         *
+         * @param parameterMap Map containing the key-value pairs.
+         * @return The Instantiator for chaining.
+         */
+        public Instantiator where(Map<String,String> parameterMap) {
+            parameters.add(parameterMap);
+            return this;
+        }
+
+        /**
+         * Set a custom library for the instantiation.
+         *
+         * @param library The custom library.
+         * @return The Instantiator for chaining.
+         */
+        public Instantiator with(CodeGeneratorLibrary library) {
+            if (this.library != null) {
+                throw new TemplateFrameworkException("Cannot set custom library twice.");
+            }
+            this.library = library;
+            return this;
+        }
+
+        /**
+         * Instantiate the CodeGenerator to a String, using the prepared parameters.
+         * This is useful for the outer-most instantiation, as it directly results in a String.
+         *
+         * @return The String resulting from the instantiation.
+         */
+        public String instantiate() {
+            if (isUsed) {
+                throw new TemplateFrameworkException("Repeated use of Instantiator not allowed.");
+            }
+            isUsed = true;
+            BaseScope scope = new BaseScope(library);
+            codeGenerator.instantiate(scope, parameters);
+            scope.close();
+            return scope.toString();
+        }
+
+        /**
+         * Instantiate the CodeGenerator into a specified scope, using the prepared parameters.
+         * This is useful for recursive instantiations.
+         *
+         * @param scope Scope into which the code is generated.
+         */
+        public void instantiate(Scope scope) {
+            if (isUsed) {
+                throw new TemplateFrameworkException("Repeated use of Instantiator not allowed.");
+            }
+            isUsed = true;
+            Scope nestedScope = new Scope(scope, scope.fuel);
+            codeGenerator.instantiate(nestedScope, parameters);
+            nestedScope.close();
+            scope.stream.addCodeStream(nestedScope.stream);
+        }
+    }
+
+    /**
+     * Create an {@link Instantiator}, which already has a first parameter key-value pair.
+     *
+     * @param paramKey The name of the parameter.
+     * @param paramValue The value to be set.
+     * @return The Instantiator.
+     */
+    public final Instantiator where(String paramKey, String paramValue) {
+        return new Instantiator(this).where(paramKey, paramValue);
+    }
+
+    /**
+     * Create an {@link Instantiator}, which already has all parameter key-value pairs from the provided map.
+     *
+     * @param parameterMap Map containing the key-value pairs.
+     * @return The Instantiator.
+     */
+    public final Instantiator where(Map<String,String> parameterMap) {
+        return new Instantiator(this).where(parameterMap);
+    }
+
+    /**
+     * Create an {@link Instantiator}, which already has set a custom library.
+     *
+     * @param library The custom library.
+     * @return The Instantiator for chaining.
+     */
+    public Instantiator with(CodeGeneratorLibrary library) {
+        return new Instantiator(this).with(library);
+    }
+
+    /**
+     * Instantiate the CodeGenerator to a String, using the prepared parameters.
+     * This is useful for the outer-most instantiation, as it directly results in a String.
+     *
+     * @return The String resulting from the instantiation.
+     */
+    public final String instantiate() {
+        return new Instantiator(this).instantiate();
+    }
+
+    /**
+     * Instantiate the CodeGenerator into a specified scope, using the prepared parameters.
+     * This is useful for recursive instantiations.
+     *
+     * @param scope Scope into which the code is generated.
+     */
+    public final void instantiate(Scope scope) {
+        new Instantiator(this).instantiate(scope);
+    }
+}