feat(optimization): add comprehensive performance optimization strategy and JIT compiler design documentation

ProgrammerKR · ProgrammerKR · commit d4b83689574c · 2025-12-12T17:15:48.000+05:30
diff --git a/deliverables/02_optimization/OPTIMIZATION_STRATEGY.md b/deliverables/02_optimization/OPTIMIZATION_STRATEGY.md
@@ -0,0 +1,28 @@
+# ProXPL Performance Optimization Strategy (phased)
+
+Prepared: 2025-12-12
+
+Overview
+- Goal: transform ProXPL interpreter into a high-performance runtime with production-grade tooling.
+- Approach: phased milestones from low-risk interpreter optimizations → efficient runtime → JIT integration → ecosystem.
+
+Milestones
+1. Hotspot Analysis & Microbenchmarks (2 weeks)
+   - Build benchmark harness targeting arithmetic, calls, string ops, allocation.
+   - Collect per-op timings, branch misprediction, cache miss rates.
+2. Bytecode & Dispatch Redesign (3 weeks)
+   - Move to register-friendly bytecode where appropriate.
+   - Use compact operand encodings and operand folding for common cases.
+   - Implement computed-goto dispatch for supported compilers and a hot-path inline dispatch for Windows/MSVC.
+3. Inline Caching & Type Specialization (4 weeks)
+   - Add monomorphic/polymorphic inline caches for property access and call targets.
+   - Specialize arithmetic ops by observed operand types and emit fast paths.
+4. Memory Management & GC (4-6 weeks)
+   - Implement a generational, moving GC (semi-space or copying nursery) + incremental major collector.
+   - Add write barriers and object header tagging for fast type checks.
+5. JIT Compiler (LLVM-backed) (8-12 weeks)
+   - Lower hot traces or functions to a compact IR, apply type-specialization, and emit native code via LLVM ORC JIT.
+6. Tooling & Ecosystem (ongoing)
+   - LSP, VSCode extension, package manager improvements, CI/CD, docs, examples.
+
+Examples and small designs are in `src/vm/vm_core_opt.c` and `deliverables/03_jit/JIT_DESIGN.md`.
diff --git a/deliverables/03_jit/JIT_DESIGN.md b/deliverables/03_jit/JIT_DESIGN.md
@@ -0,0 +1,24 @@
+# JIT Compiler Design (LLVM-based) - Overview
+
+Target: an LLVM-backed JIT that compiles hot functions/traces to native code and integrates with the interpreter.
+
+High-level flow
+- Frontend bytecode → High-level IR (typed SSA) → Optimizations (const-folding, type specialization) → LLVM IR → Native code.
+
+IR translation notes
+- Map ProXPL bytecode ops to typed IR ops (i32/float64/ptr) with explicit boxing/unboxing inserted only at boundaries.
+- Represent closures with environment pointer + function pointer pair; lower closures to structs.
+
+Sample lowering (arithmetic + call)
+- Bytecode: PUSH_CONST a; PUSH_CONST b; ADD; CALL print, argc=1
+- IR: tmp0 = load_const(a); tmp1 = load_const(b); tmp2 = add_f64(tmp0,tmp1); call print(tmp2)
+
+Memory management
+- Generated code will use runtime calling conventions to allocate and root values.
+- Use stack maps and LLVM GC metadata or explicit root registration for conservative root scanning.
+
+Integration plan
+- Keep interpreter as fallback; implement OSR and tiering: interpreter → JIT for hot functions.  
+- Use a call boundary ABI that allows compiled/native code to call interpreter functions and vice versa.
+
+See `deliverables/04_jit_examples/` for prototype code and build instructions (to be added).
diff --git a/src/vm/vm_core_opt.c b/src/vm/vm_core_opt.c
@@ -0,0 +1,163 @@
+/*
+ * vm_core_opt.c
+ *
+ * Optimized VM core loop prototype for ProXPL.
+ * - computed-goto dispatch (gcc/clang)
+ * - inline caching skeleton for call targets/property lookup
+ * - fast numeric path for binary arithmetic (type-specialized)
+ *
+ * This file is a drop-in experimental core; it is intentionally self-contained
+ * and documents the optimizations to be integrated into the main VM.
+ */
+
+#include "../../include/bytecode.h"
+#include <stdio.h>
+#include <string.h>
+
+/* Inline cache entry for call targets / property access */
+typedef struct {
+    uint32_t site_pc; /* bytecode pc of the call/property */
+    const char *target_name; /* cached name (for simple engines) */
+    void *native_ptr; /* direct native function pointer if resolved */
+    uint32_t hit_count;
+} ICEntry;
+
+/* Micro-optimization: expect/likely macros for branch prediction */
+#if defined(__GNUC__)
+#define likely(x)   __builtin_expect(!!(x), 1)
+#define unlikely(x) __builtin_expect(!!(x), 0)
+#else
+#define likely(x)   (x)
+#define unlikely(x) (x)
+#endif
+
+/* Optimized dispatch; similar to vm_dispatch but with fast-paths and IC hooks */
+int vm_execute_optimized(const Chunk *chunk) {
+    size_t ip = 0;
+    Value stack[2048];
+    int sp = 0;
+
+    /* small polymorphic inline cache for demonstration */
+    ICEntry icache[64];
+    memset(icache, 0, sizeof(icache));
+
+#if defined(__GNUC__) || defined(__clang__)
+    static void *dispatch_table[256] = { &&do_NOP };
+#define DISPATCH() goto *dispatch_table[op]
+#else
+#define DISPATCH() goto dispatch_switch
+#endif
+
+    for (;;) {
+        if (ip >= chunk->code_len) return 0;
+        uint8_t op = chunk->code[ip++];
+
+#if defined(__GNUC__) || defined(__clang__)
+        /* fill common handlers once */
+        dispatch_table[OP_NOP] = &&do_NOP;
+        dispatch_table[OP_PUSH_CONST] = &&do_PUSH_CONST;
+        dispatch_table[OP_CALL] = &&do_CALL;
+        dispatch_table[OP_ADD] = &&do_ADD_FAST;
+        dispatch_table[OP_HALT] = &&do_HALT;
+        DISPATCH();
+
+        do_NOP: { continue; }
+
+        do_PUSH_CONST: {
+            size_t read = 0;
+            uint64_t idx = read_uleb128_from(chunk->code + ip, chunk->code_len - ip, &read);
+            ip += read;
+            stack[sp++] = consttable_get(&chunk->constants, (size_t)idx);
+            continue;
+        }
+
+        /* Fast numeric add - type-specialized path */
+        do_ADD_FAST: {
+            if (unlikely(sp < 2)) return -1;
+            Value b = stack[--sp];
+            Value a = stack[--sp];
+            if (likely(a.type == VAL_NUMBER && b.type == VAL_NUMBER)) {
+                Value r; r.type = VAL_NUMBER; r.as.number = a.as.number + b.as.number;
+                stack[sp++] = r; continue;
+            }
+            /* fallback to generic add handler - simple example */
+            fprintf(stderr, "slow path: non-number add\n");
+            return -1;
+        }
+
+        do_CALL: {
+            /* inline cache lookup (very simple) */
+            size_t saved_ip = ip;
+            size_t read = 0;
+            uint64_t idx = read_uleb128_from(chunk->code + ip, chunk->code_len - ip, &read);
+            ip += read;
+            if (ip >= chunk->code_len) return -1;
+            uint8_t argc = chunk->code[ip++];
+
+            Value callee = consttable_get(&chunk->constants, (size_t)idx);
+            /* probe icache for site */
+            uint32_t site = (uint32_t)(saved_ip & 63);
+            ICEntry *ent = &icache[site];
+            if (ent->site_pc == (uint32_t)saved_ip && ent->native_ptr) {
+                ent->hit_count++;
+                /* call native_ptr directly (demo only) */
+                typedef Value (*native_fn)(Value*, int);
+                native_fn fn = (native_fn)ent->native_ptr;
+                Value ret = fn(&stack[sp-argc], (int)argc);
+                sp -= argc; stack[sp++] = ret; continue;
+            }
+
+            /* resolve and fill cache (demo: only 'print') */
+            if (callee.type == VAL_STRING && strcmp(callee.as.string.chars, "print") == 0) {
+                /* cache a sentinel to native print handler */
+                ent->site_pc = (uint32_t)saved_ip;
+                ent->target_name = callee.as.string.chars;
+                ent->native_ptr = NULL; /* optionally assign a function pointer */
+                /* fallback: implement print directly */
+                for (int i = (int)argc - 1; i >= 0; --i) {
+                    Value arg = stack[--sp];
+                    if (arg.type == VAL_STRING) fputs(arg.as.string.chars, stdout);
+                    else if (arg.type == VAL_NUMBER) printf("%g", arg.as.number);
+                    else if (arg.type == VAL_BOOL) fputs(arg.as.boolean?"true":"false", stdout);
+                    else fputs("<obj>", stdout);
+                    if (i) putchar(' ');
+                }
+                putchar('\n');
+                Value r = make_null_const(); stack[sp++] = r; continue;
+            }
+
+            fprintf(stderr, "unsupported call target\n"); return -1;
+        }
+
+        do_HALT: { return 0; }
+
+#else
+dispatch_switch:
+        switch (op) {
+            case OP_NOP: break;
+            case OP_PUSH_CONST: {
+                size_t read=0; uint64_t idx = read_uleb128_from(chunk->code+ip, chunk->code_len-ip, &read); ip+=read;
+                stack[sp++] = consttable_get(&chunk->constants, (size_t)idx);
+            } break;
+            case OP_ADD: {
+                if (sp<2) return -1; Value b = stack[--sp]; Value a = stack[--sp];
+                if (a.type==VAL_NUMBER && b.type==VAL_NUMBER) { Value r; r.type=VAL_NUMBER; r.as.number=a.as.number+b.as.number; stack[sp++]=r; }
+                else { fprintf(stderr,"slow path: non-number add\n"); return -1; }
+            } break;
+            case OP_CALL: {
+                size_t read=0; uint64_t idx = read_uleb128_from(chunk->code+ip, chunk->code_len-ip, &read); ip+=read;
+                if (ip>=chunk->code_len) return -1; uint8_t argc = chunk->code[ip++];
+                Value callee = consttable_get(&chunk->constants,(size_t)idx);
+                if (callee.type==VAL_STRING && strcmp(callee.as.string.chars,"print")==0) {
+                    for (int i=(int)argc-1;i>=0;--i){ Value arg=stack[--sp]; if (arg.type==VAL_STRING) fputs(arg.as.string.chars, stdout); else if (arg.type==VAL_NUMBER) printf("%g",arg.as.number); else fputs("<obj>",stdout); if (i) putchar(' ');} putchar('\n'); Value r = make_null_const(); stack[sp++]=r; break;
+                }
+                fprintf(stderr,"unsupported call target\n"); return -1;
+            }
+            case OP_HALT: return 0;
+            default: fprintf(stderr,"unhandled opcode %u\n",op); return -1;
+        }
+#endif
+    }
+
+    return 0;
+}
diff --git a/tools/bench/bench_simple.c b/tools/bench/bench_simple.c
@@ -0,0 +1,54 @@
+/* bench_simple.c
+ * A tiny microbenchmark that constructs a numeric-add heavy Chunk and
+ * executes it repeatedly to measure interpreter throughput.
+ * This file expects the project to expose Chunk/bytecode helpers and
+ * a vm_run_chunk_simple() entry in `src/vm/vm_dispatch.c`.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+#include "../../include/bytecode.h"
+
+extern int vm_run_chunk_simple(const Chunk *chunk);
+
+#if defined(_WIN32)
+#include <windows.h>
+static double now_seconds(void) {
+    static LARGE_INTEGER freq;
+    LARGE_INTEGER cnt;
+    if (freq.QuadPart == 0) QueryPerformanceFrequency(&freq);
+    QueryPerformanceCounter(&cnt);
+    return (double)cnt.QuadPart / (double)freq.QuadPart;
+}
+#else
+static double now_seconds(void) {
+    struct timespec t;
+    clock_gettime(CLOCK_MONOTONIC, &t);
+    return t.tv_sec + t.tv_nsec * 1e-9;
+}
+#endif
+
+int main(int argc, char **argv) {
+    (void)argc; (void)argv;
+    /* Build a simple chunk: push 100 constants then add them pairwise */
+    Chunk c; initChunk(&c);
+    for (int i = 0; i < 100; ++i) {
+        emit_constant(&c, NUMBER_VAL((double)i));
+    }
+    /* Create add sequence */
+    for (int i = 0; i < 99; ++i) emit_opcode(&c, OP_ADD);
+    emit_opcode(&c, OP_HALT);
+
+    int runs = 500;
+    double t0 = now_seconds();
+    for (int i = 0; i < runs; ++i) {
+        int r = vm_run_chunk_simple(&c);
+        if (r != 0) { fprintf(stderr, "vm returned %d\n", r); break; }
+    }
+    double t1 = now_seconds();
+    printf("runs=%d total=%.6fs avg=%.6fms\n", runs, t1-t0, (t1-t0)/runs*1000.0);
+
+    freeChunk(&c);
+    return 0;
+}
diff --git a/tools/bench/build_msvc.ps1 b/tools/bench/build_msvc.ps1
@@ -0,0 +1,31 @@
+#!/usr/bin/env pwsh
+<#
+  build_msvc.ps1
+  Build the bench_simple.exe using MSVC `cl.exe`.
+
+  Usage: run this inside a "Developer Command Prompt for VS" or after running
+  `VsDevCmd.bat` so `cl.exe` and the toolchain are on PATH.
+#>
+
+if (-not (Get-Command cl.exe -ErrorAction SilentlyContinue)) {
+    Write-Error "cl.exe not found in PATH. Run this script from 'Developer Command Prompt for VS' or run VsDevCmd.bat first."
+    exit 1
+}
+
+$root = (Resolve-Path "$PSScriptRoot\..\..").Path
+$include = Join-Path $root "include"
+$src = Join-Path $root "src"
+$bench = Join-Path $PSScriptRoot "bench_simple.c"
+$files = @(
+    '"' + $bench + '"',
+    '"' + (Join-Path $src "vm\vm_dispatch.c") + '"',
+    '"' + (Join-Path $src "vm\bytecode.c") + '"'
+)
+
+$incs = "/I""$include"" /I""$src"""
+$clopts = "/nologo /O2 /W3 /std:c11"
+$outfile = "bench_simple.exe"
+
+$cmd = "cl.exe $clopts $incs /Fe:$outfile " + ($files -join ' ')
+Write-Host "Running: $cmd"
+Invoke-Expression $cmd
diff --git a/tools/lsp/README.md b/tools/lsp/README.md
@@ -0,0 +1,17 @@
+# ProXPL LSP - Starter Notes
+
+This folder will contain the language server implementation (LSP) supporting:
+- syntax highlighting
+- auto-completion
+- diagnostics
+- go-to-definition
+- signature help
+
+Planned approach
+- Use Node.js + TypeScript with `vscode-languageserver` for rapid development.
+- Alternatively provide a lightweight Python `pygls` server for contributors preferring Python.
+
+Next steps
+1. Add grammar-based parser bindings (re-use `src/parser` AST).  
+2. Implement basic diagnostics by running the existing parser and type checker.
+3. Implement completion/signature by walking the AST and symbol tables.
