WIP: Multiplicity — per-runtime isolation for concurrent Perl interpreters

AGENTS.md

@@ -198,6 +198,20 @@ The perl_test_runner.pl sets these automatically based on the test file being ru
 
 ### Commits
 
+- **Single quotes in commit messages:** The `$(cat <<'EOF' ... EOF)` heredoc pattern breaks when the message body contains single quotes (e.g., Perl's `$_`, `don't`). Write the message to a temp file and use `git commit -F` instead:
+  ```bash
+  cat > /tmp/commit_msg.txt << 'ENDMSG'
+  feat: description here
+
+  Body with single quotes like $_ and don't is fine.
+
+  Generated with [TOOL_NAME](TOOL_DOCS_URL)
+
+  Co-Authored-By: TOOL_NAME <TOOL_BOT_EMAIL>
+  ENDMSG
+  git commit -F /tmp/commit_msg.txt
+  ```
+  Replace `TOOL_NAME`, `TOOL_DOCS_URL`, and `TOOL_BOT_EMAIL` as described in [AI_POLICY.md](AI_POLICY.md).
 - Reference the design doc or issue in commit messages when relevant
 - Use conventional commit format when possible
 - **Write commit messages to a file** to avoid shell quoting issues (apostrophes, backticks, special characters). Use `git commit -F /tmp/commit_msg.txt` instead of `-m`:

dev/design/README.md

@@ -113,9 +113,9 @@ When adding new design documents:
 
 For the most important architectural decisions and current work, check:
 
-- **multiplicity.md** - Multiple independent Perl runtimes (enables fork/threads/web concurrency)
+- **concurrency.md** - Unified concurrency design (supersedes multiplicity.md, fork.md, threads.md). Includes multiplicity demo and progress tracking.
 - **jsr223-perlonjava-web.md** - JSR-223 compliance and web server integration
-- **fork.md** / **threads.md** - Concurrency model and limitations
+- **multiplicity.md** / **fork.md** / **threads.md** - Superseded by concurrency.md
 
 These represent major architectural directions for the project.
 

dev/sandbox/multiplicity/MultiplicityDemo.java

@@ -0,0 +1,136 @@
+package org.perlonjava.demo;
+
+import org.perlonjava.app.cli.CompilerOptions;
+import org.perlonjava.app.scriptengine.PerlLanguageProvider;
+import org.perlonjava.runtime.io.StandardIO;
+import org.perlonjava.runtime.runtimetypes.*;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Demonstrates PerlOnJava's "multiplicity" feature: multiple independent Perl
+ * interpreters running concurrently within a single JVM process.
+ *
+ * Each interpreter has its own global variables, regex state, @INC, %ENV, etc.
+ * They share the JVM heap; generated classes are loaded into each runtime's own
+ * ClassLoader and become eligible for GC once the runtime is discarded.
+ *
+ * Usage:
+ *   java -cp target/perlonjava-5.42.0.jar \
+ *        org.perlonjava.demo.MultiplicityDemo script1.pl script2.pl ...
+ *
+ * Or with the helper script:
+ *   ./dev/sandbox/multiplicity/run_multiplicity_demo.sh script1.pl script2.pl ...
+ *
+ * See also: dev/design/concurrency.md (Multiplicity Demo section)
+ */
+public class MultiplicityDemo {
+
+    public static void main(String[] args) throws Exception {
+        if (args.length == 0) {
+            System.err.println("Usage: MultiplicityDemo <script1.pl> [script2.pl] ...");
+            System.err.println("Runs each Perl script in its own interpreter, concurrently.");
+            System.exit(1);
+        }
+
+        // Read all script files upfront
+        List<String> scriptNames = new ArrayList<>();
+        List<String> scriptSources = new ArrayList<>();
+        for (String arg : args) {
+            Path p = Path.of(arg);
+            if (!Files.isRegularFile(p)) {
+                System.err.println("Error: not a file: " + arg);
+                System.exit(1);
+            }
+            scriptNames.add(p.getFileName().toString());
+            scriptSources.add(Files.readString(p));
+        }
+
+        int n = scriptNames.size();
+        System.out.println("=== PerlOnJava Multiplicity Demo ===");
+        System.out.println("Starting " + n + " independent Perl interpreter(s)...\n");
+
+        // Per-thread output capture
+        ByteArrayOutputStream[] outputs = new ByteArrayOutputStream[n];
+        long[] durations = new long[n];
+        Throwable[] errors = new Throwable[n];
+
+        Thread[] threads = new Thread[n];
+        for (int i = 0; i < n; i++) {
+            final int idx = i;
+            final String name = scriptNames.get(i);
+            final String source = scriptSources.get(i);
+            outputs[idx] = new ByteArrayOutputStream();
+
+            threads[i] = new Thread(() -> {
+                try {
+                    // --- Create an independent PerlRuntime for this thread ---
+                    PerlRuntime.initialize();
+
+                    // Redirect this interpreter's STDOUT to a private buffer.
+                    // RuntimeIO.setStdout() operates on the current thread's PerlRuntime.
+                    PrintStream ps = new PrintStream(outputs[idx], true);
+                    RuntimeIO customOut = new RuntimeIO(new StandardIO(ps, true));
+                    RuntimeIO.setStdout(customOut);
+                    RuntimeIO.setSelectedHandle(customOut);
+                    RuntimeIO.setLastWrittenHandle(customOut);
+
+                    // Set up compiler options
+                    CompilerOptions options = new CompilerOptions();
+                    options.code = source;
+                    options.fileName = name;
+
+                    // Use executePerlCode() which handles the full lifecycle:
+                    // - GlobalContext.initializeGlobals() (per-runtime, under COMPILE_LOCK)
+                    // - Tokenize, parse, compile (under COMPILE_LOCK — serialized)
+                    // - Run UNITCHECK, CHECK, INIT blocks
+                    // - Execute the main code (no lock — concurrent)
+                    // - Run END blocks
+                    long t0 = System.nanoTime();
+                    PerlLanguageProvider.executePerlCode(options, true);
+                    durations[idx] = System.nanoTime() - t0;
+
+                    // Flush buffered output
+                    RuntimeIO.flushFileHandles();
+
+                } catch (Throwable t) {
+                    errors[idx] = t;
+                }
+            }, "perl-" + name);
+        }
+
+        // Start all threads
+        long wallStart = System.nanoTime();
+        for (Thread t : threads) t.start();
+        for (Thread t : threads) t.join(60_000);  // 60s safety timeout
+        long wallElapsed = System.nanoTime() - wallStart;
+
+        // --- Print results ---
+        System.out.println("=== Output from each interpreter ===\n");
+        for (int i = 0; i < n; i++) {
+            System.out.println("--- " + scriptNames.get(i) + " ---");
+            if (errors[i] != null) {
+                System.out.println("  ERROR: " + errors[i].getMessage());
+                errors[i].printStackTrace(System.out);
+            } else {
+                // Indent each line for readability
+                String out = outputs[i].toString().stripTrailing();
+                for (String line : out.split("\n")) {
+                    System.out.println("  " + line);
+                }
+                System.out.printf("  (executed in %.1f ms)%n", durations[i] / 1_000_000.0);
+            }
+            System.out.println();
+        }
+
+        System.out.printf("=== All %d interpreters finished (wall time: %.1f ms) ===%n",
+                n, wallElapsed / 1_000_000.0);
+    }
+}

dev/sandbox/multiplicity/README.md

@@ -0,0 +1,45 @@
+# Multiplicity Demo
+
+Demonstrates PerlOnJava's "multiplicity" feature: multiple independent Perl
+interpreters running concurrently within a single JVM process.
+
+Each interpreter has its own global variables, regex state, `@INC`, `%ENV`,
+current working directory, process ID (`$$`), etc. They share the JVM heap;
+generated classes are loaded into each runtime's own ClassLoader and become
+eligible for GC once the runtime is discarded.
+
+## Quick Start
+
+```bash
+# Build the project first
+make dev
+
+# Run with the bundled demo scripts
+./dev/sandbox/multiplicity/run_multiplicity_demo.sh
+
+# Run with custom scripts
+./dev/sandbox/multiplicity/run_multiplicity_demo.sh script1.pl script2.pl
+
+# Run all unit tests concurrently (stress test)
+./dev/sandbox/multiplicity/run_multiplicity_demo.sh src/test/resources/unit/*.t
+```
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `MultiplicityDemo.java` | Java driver that creates N threads, each with its own `PerlRuntime` |
+| `run_multiplicity_demo.sh` | Shell wrapper that compiles and runs the demo |
+| `multiplicity_script1.pl` | Demo script: basic variable isolation |
+| `multiplicity_script2.pl` | Demo script: regex state isolation |
+| `multiplicity_script3.pl` | Demo script: module loading isolation |
+
+## Current Status
+
+- **122/126** unit tests pass with 126 concurrent interpreters
+- Only 4 failures remain: `tie_*.t` (pre-existing `DESTROY` not implemented)
+
+## Design Document
+
+See [dev/design/concurrency.md](../../design/concurrency.md) for the full
+concurrency design, implementation phases, and progress tracking.

dev/sandbox/multiplicity/multiplicity_script1.pl

@@ -0,0 +1,26 @@
+# multiplicity_script1.pl — Demonstrates isolated state in interpreter 1
+use strict;
+use warnings;
+
+my $id = "Interpreter-1";
+$_ = "Hello from $id";
+
+# Set a global variable
+our $shared_test = 42;
+
+# Regex match — regex state ($1, $&, etc.) should be isolated
+"The quick brown fox" =~ /(\w+)\s+(\w+)/;
+my $match = "$1 $2";
+
+# Simulate some work
+my $sum = 0;
+for my $i (1..1000) {
+    $sum += $i;
+}
+
+print "[$id] \$_ = $_\n";
+print "[$id] Regex match: $match\n";
+print "[$id] \$shared_test = $shared_test\n";
+print "[$id] Sum 1..1000 = $sum\n";
+print "[$id] \@INC has " . scalar(@INC) . " entries\n";
+print "[$id] Done!\n";

dev/sandbox/multiplicity/multiplicity_script2.pl

@@ -0,0 +1,26 @@
+# multiplicity_script2.pl — Demonstrates isolated state in interpreter 2
+use strict;
+use warnings;
+
+my $id = "Interpreter-2";
+$_ = "Greetings from $id";
+
+# This variable should NOT see interpreter 1's value
+our $shared_test = 99;
+
+# Different regex — state should not leak from interpreter 1
+"2025-04-10" =~ /(\d{4})-(\d{2})-(\d{2})/;
+my $match = "$1/$2/$3";
+
+# Different computation
+my $product = 1;
+for my $i (1..10) {
+    $product *= $i;
+}
+
+print "[$id] \$_ = $_\n";
+print "[$id] Regex match: $match\n";
+print "[$id] \$shared_test = $shared_test\n";
+print "[$id] 10! = $product\n";
+print "[$id] \@INC has " . scalar(@INC) . " entries\n";
+print "[$id] Done!\n";

dev/sandbox/multiplicity/multiplicity_script3.pl

@@ -0,0 +1,26 @@
+# multiplicity_script3.pl — Demonstrates isolated state in interpreter 3
+use strict;
+use warnings;
+
+my $id = "Interpreter-3";
+$_ = "Bonjour from $id";
+
+# Independent global
+our $shared_test = -1;
+
+# Yet another regex
+"foo\@bar.com" =~ /(\w+)\@(\w+)\.(\w+)/;
+my $match = "user=$1 domain=$2 tld=$3";
+
+# Fibonacci
+my @fib = (0, 1);
+for my $i (2..20) {
+    push @fib, $fib[-1] + $fib[-2];
+}
+
+print "[$id] \$_ = $_\n";
+print "[$id] Regex match: $match\n";
+print "[$id] \$shared_test = $shared_test\n";
+print "[$id] Fib(20) = $fib[20]\n";
+print "[$id] \@INC has " . scalar(@INC) . " entries\n";
+print "[$id] Done!\n";

dev/sandbox/multiplicity/run_multiplicity_demo.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+#
+# Compile and run the Multiplicity Demo.
+#
+# Usage:
+#   ./dev/sandbox/multiplicity/run_multiplicity_demo.sh [script1.pl script2.pl ...]
+#
+# If no scripts are given, runs the three bundled demo scripts.
+#
+# See also: dev/design/concurrency.md (Multiplicity Demo section)
+#
+set -euo pipefail
+cd "$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"
+
+DEMO_SRC="dev/sandbox/multiplicity/MultiplicityDemo.java"
+DEMO_DIR="dev/sandbox/multiplicity"
+
+# Find the fat JAR the same way jperl does
+if [ -f "target/perlonjava-5.42.0.jar" ]; then
+    JAR="target/perlonjava-5.42.0.jar"
+elif [ -f "perlonjava-5.42.0.jar" ]; then
+    JAR="perlonjava-5.42.0.jar"
+else
+    echo "Fat JAR not found. Run 'make dev' first."
+    exit 1
+fi
+
+# Compile the demo against the fat JAR
+echo "Compiling MultiplicityDemo.java..."
+javac -d "$DEMO_DIR" -cp "$JAR" "$DEMO_SRC"
+
+# Default scripts if none provided
+if [ $# -eq 0 ]; then
+    set -- dev/sandbox/multiplicity/multiplicity_script1.pl \
+           dev/sandbox/multiplicity/multiplicity_script2.pl \
+           dev/sandbox/multiplicity/multiplicity_script3.pl
+fi
+
+echo ""
+# Run with the demo class prepended to the classpath
+java -cp "$DEMO_DIR:$JAR" org.perlonjava.demo.MultiplicityDemo "$@"

src/main/java/org/perlonjava/app/cli/Main.java

@@ -4,6 +4,7 @@
 import org.perlonjava.runtime.runtimetypes.ErrorMessageUtil;
 import org.perlonjava.runtime.runtimetypes.GlobalVariable;
 import org.perlonjava.runtime.runtimetypes.PerlExitException;
+import org.perlonjava.runtime.runtimetypes.PerlRuntime;
 import org.perlonjava.runtime.runtimetypes.RuntimeScalar;
 
 import java.util.Locale;
@@ -26,6 +27,9 @@ public class Main {
      * @param args Command-line arguments.
      */
     public static void main(String[] args) {
+        // Initialize the PerlRuntime for the main thread
+        PerlRuntime.initialize();
+
         CompilerOptions parsedArgs = ArgumentParser.parseArguments(args);
 
         if (parsedArgs.code == null) {