Performance: Reduce JIT compile-time overhead (target under 50ms cold start)

[PurHur]

Problem

README notes ~0.2s baseline to parse and compile a file in bin/jit.php. For web requests, compile-on-every-run dominates unless using AOT (phpc build / phpc serve --aot).

examples/001-SimpleWeb benchmark table shows bin/jit.php ~0.11s vs ./compiled ~0.0016s runtime — production path is AOT; JIT cold compile still matters for #207 phpc serve --jit and dev workflows.

Goal

Measurable compile-time reduction for typical single-file web scripts (<200 lines), targeting <50ms cold compile on reference hardware (document baseline in issue/PR).

Implementation hints

Measure first

Script	Purpose
script/bench-compile.php (new)	Split timings: parse → CFG → opcodes → LLVM emit → link
make bench	Extend or document JIT compile column separate from runtime

Profile hot paths:

• lib/Compiler.php — avoid redundant recompilation of unchanged files
• lib/JIT.php — module creation, PHPLLVM context init
• lib/JIT.pre / opcode lowering

Optimization ideas (prioritized)

1. On-disk module cache — coordinate JIT: On-disk compile cache for warm requests #153 (phpc cache dir keyed by sha256(file)+compilerVersion)
2. mtime short-circuit — skip LLVM if source + deps unchanged
3. Shared stdlib JIT object — precompile ext/standard hot builtins once per process
4. Lazy block compile — defer cold blocks until executed (larger change)
5. Self-host — long-term README vision; out of scope for first PR

Deployment guidance (docs)

• Production: phpc build + phpc serve --aot or CGI binary (Web: CGI/1.1 request driver (stdin/stdout, env, Status line) #50)
• Dev: VM default; --jit when Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 lands

Acceptance criteria

script/bench-compile.php prints before/after table for examples/001-SimpleWeb/example.php in README or comment on this issue.

Target: documented reduction (e.g. 200ms → <50ms) OR explicit rationale why target deferred (with #153 cache as recommended path).

Verification (local / Docker only)

docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev php script/bench-compile.php

No GitHub Actions.

Dependencies

• JIT: On-disk compile cache for warm requests #153 on-disk JIT cache (likely shares cache dir layout)
• Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 serve --jit consumer
• CI: Run JIT compliance tests in CI (fix LLVM skip in PHPUnit) #98 JIT compliance must run to validate optimizations

Related

• AOT: Project build mode (entry file + dependency graph) #59 AOT project build (production path)
• AOT: Debug symbols and source map for compiled binaries (-y flag) #75 debug symbols (may affect compile time)
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 3

[PurHur]

Implementation hints (batch 78 — backlog architect)

Benchmark harness (add first)

Artifact	Purpose
script/bench-jit-compile.php	Time parse → CFG → opcodes → LLVM module → link; print CSV row
test/unit/JitCompileBenchTest.php	@group slow — assert compile ms < threshold on examples/000-HelloWorld/example.php
Makefile bench-jit-compile	Document baseline in PR; no GHA

php script/bench-jit-compile.php examples/001-SimpleWeb/example.php
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  php script/bench-jit-compile.php examples/001-SimpleWeb/example.php

Hot paths (profile order)

1. PHPLLVM\Context init — reuse across requests (JIT: On-disk compile cache for warm requests #153 on-disk cache)
2. lib/Compiler.php — skip re-parse when mtime unchanged
3. lib/JIT.php — module reuse; avoid re-emitting stdlib builtins (shared stdlib JIT object)
4. lib/JIT.pre — opcode lowering batching

Dependencies

• JIT: On-disk compile cache for warm requests #153 on-disk JIT cache (primary win for Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 phpc serve --jit)
• Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 — per-request compile consumer
• Orthogonal: AOT path already sub-ms runtime (examples/README.md benchmark table)

Verify

Local/Docker only — not GitHub Actions (#394 ✅).

[PurHur]

Implementation hints (May 2026 backlog pass)

Bench harness (add first)

File	Purpose
script/bench-compile.php	time parse / CFG / opcodes / LLVM emit / (optional) link for one entry file
Makefile bench-compile	Wrapper calling script inside Docker on harness

Example:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php script/bench-compile.php examples/001-SimpleWeb/example.php'

Likely hot paths (profile before micro-opts)

1. lib/JIT.php — LLVM context creation per run (JIT: On-disk compile cache for warm requests #153 should amortize)
2. lib/Compiler.php — re-parse unchanged includes when project graph grows (Language: JIT include/require compile-time lowering (#54 follow-up) #475 / JIT: Project include lowering for 003-MiniWebApp (phpc serve --jit blocked on #475) #1770)
3. ext/standard — duplicate JIT module emission; shared stdlib object file (stretch)

Gate / CI

• Not a ci-local.sh gate until noise stable; document baseline in PR description
• Consumer: Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 phpc serve --jit, Testing: phpc serve --jit e2e smoke (001 SimpleWeb + 003 MiniWebApp) #2274 serve-JIT e2e

Verification (harness-safe)

Do not use docker run -v "$(pwd):/compiler" on Runforge (empty mount). Prefer ./script/docker-exec.sh or make test-harness.

[PurHur]

claim: cursor-agent-lane-b — starting this run (bench harness from #1898 landed; targeting cold compile reduction toward <50ms)

[PurHur]

release: cursor-agent-lane-b — deferring; continuing lane B language issue #3658 via open PR #3857 instead

[PurHur]

claim: cursor-agent-lane-b — starting this run (cold JIT compile reduction toward <50ms; bench harness #1898 landed)

[PurHur]

Progress (cursor-agent-lane-b)

Implemented lazy ext/* JIT lowering to cut cold compile overhead:

• Default-on for MCJIT embed: skip eager loadJitCompileModuleFuncs (~363 stdlib funcs) and compile on first reference via resolveFunctionProxy.
• Opt-out: PHP_COMPILER_JIT_LAZY_BUILTINS=0
• Cache fingerprint includes lazy policy (JIT: On-disk compile cache for warm requests #153 compatibility)

Verification (Docker)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter "JitLazyBuiltinsTest|BenchCompileScriptTest"'

MCJIT bench/execute still segfaults in this harness (jit-runtime-probe exit 1); unit coverage guards policy + cache key.

PR: (creating)

[PurHur]

PR: #3883

[PurHur]

Merged via PR #3883 — lazy ext/* JIT lowering for cold compile.

What landed

• MCJIT embed mode skips eager loadJitCompileModuleFuncs (~363 ext/standard functions); each registered module function is lowered on first resolveFunctionProxy reference instead.
• Default-on for bin/jit.php / embed JIT; opt out with PHP_COMPILER_JIT_LAZY_BUILTINS=0.
• Lazy policy included in on-disk cache fingerprint (CompileCache) so eager/lazy bitcode is not mixed.
• JitLazyBuiltinsTest + cache key tests guard the policy.

Verification (Docker)

```bash
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter "JitLazyBuiltinsTest|BenchCompileScriptTest|JitCompileCacheTest::testComputeKey|JitCompileCacheTest::testIsFresh"'

OK, but incomplete (2 skipped MCJIT bench probes in harness)

```

PR: #3883