# yk

A [[meta-tracing]] system that automatically derives JIT compilers from C interpreters. Add ~400 lines to an existing interpreter, get ~2x geometric mean speedup while retaining full compatibility with the reference implementation.

## What it does

yk instruments C interpreters at compile time using a modified LLVM (ykllvm). When it detects hot loops in guest programs, it traces the interpreter's execution, optimizes the trace, and compiles it to machine code.

The key value proposition: unlike RPython or Truffle, you don't write a new interpreter. You take the existing reference implementation (PUC Lua, MicroPython) and add JIT capabilities.

## How it works

1. Compile interpreter with ykllvm (replaces cc/ld in Makefile)
2. Add `YkLocation` markers at interpreter loop points
3. ykllvm inserts `__yk_trace_basicblock(id)` at control flow points
4. At runtime, hot loops trigger trace recording
5. Traces are optimized and compiled to machine code
6. JIT code executes with guards that deoptimize on speculation failure

## Key APIs

```c
// Mark a control point (interpreter loop)
YkLocation loc = yk_location_new();
while (true) {
    yk_mt_control_point(mt, &loc);
    // interpreter dispatch
}

// Burn a runtime value as a trace constant
opcode = yk_promote(GET_OPCODE(i));

// Mark a function as pure (enables constant propagation)
__attribute__((yk_idempotent))
int get_opcode(Instruction i) { ... }
```

## Projects using yk

- **yklua** — PUC Lua with JIT, tracks upstream trivially (5.4.6 → 5.5.0 in 2 hours)
- **ykmicropython** — MicroPython with JIT
- **ykllvm** — LLVM fork with trace instrumentation

## Performance

~2x geometric mean on benchmarks, some 4-6x. Less than hand-optimized LuaJIT, but LuaJIT is stuck on Lua 5.1 and can't track language updates.

## Limitations

- Alpha-stage software, x64 only
- Missing optimizations, some TODO halts
- Funded research project (Shopify, Royal Academy of Engineering)
- Deoptimization adds complexity vs native interpreters

See [[retrofitting-jit-c-interpreters]] for the full technical explanation.

---

Repo: https://github.com/ykjit/yk