feat: Interpreter fallback for large subroutines

[fglock]

Summary

Implements interpreter fallback for large subroutines that exceed the JVM's 65,535 byte method size limit. When compilation fails due to size limits, the system automatically falls back to the bytecode interpreter, which has no size restrictions.

Key Changes

1. Fixed Critical Bug in RuntimeScalar Management (614f949)

Root Cause: SubroutineParser extracted a local reference to the RuntimeCode placeholder, which became stale when InterpretedCode replaced codeRef.value.

Solution:

• SubroutineParser: Never use persistent local RuntimeCode references
• For CompiledCode: Fill in existing placeholder via codeRef.value
• For InterpretedCode: Replace codeRef.value entirely
• RuntimeCode: Add compilerSupplier check to all static apply methods

Ensures:

• RuntimeScalar wrapper in globalCodeRefs is single source of truth
• All access goes through codeRef.value (no stale references)
• Lazy compilation works for both CompiledCode and InterpretedCode
• Polymorphic dispatch works correctly for both code types

2. Infrastructure Additions

• CompiledCode class: Wrapper for compiled RuntimeCode with generated class reference
• Unified API: EmitterMethodCreator.createRuntimeCode() returns either CompiledCode or InterpretedCode
• Test infrastructure: Large subroutine tests (15,000 statements)
• Debug output: Optional compilation fallback path messages
• Larger EVAL_TRY offsets: 4-byte offsets to support large code blocks

Environment Variable

JPERL_USE_INTERPRETER_FALLBACK=1    # Enable interpreter fallback
                                     # (skips AST splitter for faster testing)

When set:

• Skips AST splitting retry on "Method too large" errors
• Directly falls back to interpreter backend
• Shows fallback path messages

When not set:

• Tries AST splitting first (existing behavior)
• Only uses interpreter if AST splitting fails
• Maintains backward compatibility

Architecture

Compilation Flow

SubroutineParser
  └─> Creates placeholder RuntimeCode
  └─> Stores Supplier for lazy compilation
  
First Invocation
  └─> RuntimeCode.apply() runs Supplier
      └─> EmitterMethodCreator.createRuntimeCode()
          ├─> Try JVM compilation
          │   └─> Success: CompiledCode
          │       └─> Fill placeholder with MethodHandle
          └─> Catch MethodTooLargeException
              ├─> If JPERL_USE_INTERPRETER_FALLBACK: Skip AST splitter
              └─> Fall back to BytecodeCompiler
                  └─> InterpretedCode
                      └─> REPLACE codeRef.value entirely

Single Source of Truth

// Global storage
RuntimeScalar codeRef = GlobalVariable.getGlobalCodeRef(fullName);

// ✅ Correct: Access via codeRef.value each time
RuntimeCode placeholder = (RuntimeCode) codeRef.value;
placeholder.methodHandle = ...;

// ❌ Wrong: Local reference becomes stale
RuntimeCode code = (RuntimeCode) codeRef.value;
// ... later ...
code.methodHandle = ...;  // Modifies wrong object!

Testing

✅ All unit tests pass (make test)
✅ Large subroutines compile to interpreter (15,000 statements)
✅ Interpreter executes correctly with correct results
✅ Normal compilation path unchanged (AST splitter still works)
✅ No "Undefined subroutine" errors
✅ Polymorphic dispatch works (both CompiledCode and InterpretedCode)
✅ Code references work correctly

Test Results

# Normal compilation (AST splitter path)
$ ./jperl large_sub.pl
large_sub result: 112507500
OK

# Interpreter fallback enabled
$ JPERL_USE_INTERPRETER_FALLBACK=1 ./jperl large_sub.pl
Note: Method too large, skipping AST splitter (interpreter fallback enabled).
Note: Method too large after AST splitting, using interpreter backend.
large_sub result: 112507500
OK

# Polymorphic dispatch (mixed compiled/interpreted)
$ JPERL_USE_INTERPRETER_FALLBACK=1 ./jperl polymorphic_test.pl
small: 42
medium: 500500
large: 50005000
OK: All subroutines returned correct values
via coderef - small: 42, medium: 500500, large: 50005000
OK: Code references work correctly

Benefits

1. No size limits: Subroutines can be arbitrarily large
2. Seamless fallback: Automatic, no user intervention needed
3. Binary compatibility: InterpretedCode and CompiledCode are indistinguishable
4. Performance: Compiled code still fast, interpreter only for edge cases
5. Testing: Easy to test interpreter path with environment variable

Design Principles

• Single Source of Truth: RuntimeScalar wrapper is authoritative
• No Local References: Never extract and persist RuntimeCode from wrapper
• Lazy Compilation: Supplier pattern preserved for both code types
• Polymorphic Dispatch: Virtual method dispatch works for both implementations

🤖 Generated with Claude Code