jitto 🚀

jitto is a lightweight, zero-dependency Universal Just-In-Time (JIT) Compilation Engine for Python language creators, interpreters, and compilers.

It was created to power custom programming languages—such as new_eval—by ingesting their AST nodes and compiling them directly into native ARM64 (Apple Silicon) and 64-bit x86 (Intel/AMD) machine code for hardware-speed execution.

Key Features

• Universal AST Agnostic: Ingests AST nodes from custom language parsers (like new_eval) without requiring custom glue code.
• Multi-Architecture Support: Automatically detects and emits native ARM64 (AArch64) or x86-64 machine code instructions.
• Zero External Dependencies: Uses pure Python built-in modules (mmap, ctypes, struct).
• Variable Scope Binding: Evaluates expressions with dynamic variable environment dictionaries (variables={"x": 10}).
• Thread-Safe Memory Allocation: Verified under concurrent multi-threaded JIT compilation workloads.

Installation

pip install jitto

Or for local development:

pip install -e .

Quickstart

1-Liner JIT Execution

import ast
from jitto import run_jit

# Compiles AST directly to native machine code & executes on CPU hardware
result = run_jit(ast.parse("100 - (15 * 4)", mode="eval"))
print("JIT Execution Result:", result)  # Outputs: 40

Universal AST Examples

1. Integration Example: Giving new_eval a Native JIT Compiler

If your custom language (like new_eval) uses @dataclass nodes or custom parser objects:

from dataclasses import dataclass
from jitto import run_jit

# AST nodes from the new_eval language parser
@dataclass
class Int_Node:
    value: int

@dataclass
class BinOps_Node:
    left: any
    ops: str
    right: any

# new_eval AST: 10 + (20 * 3)
new_eval_ast = BinOps_Node(
    left=Int_Node(10),
    ops="+",
    right=BinOps_Node(left=Int_Node(20), ops="*", right=Int_Node(3))
)

# Run new_eval AST natively on hardware CPU!
result = run_jit(new_eval_ast)
print("new_eval JIT Execution Result:", result)  # Outputs: 70

2. JSON / Dictionary AST

from jitto import run_jit

dict_ast = {
    "type": "BinOp",
    "op": "*",
    "left": {
        "type": "BinOp",
        "op": "+",
        "left": {"type": "Constant", "value": 5},
        "right": {"type": "Constant", "value": 15}
    },
    "right": {"type": "Constant", "value": 4}
}

result = run_jit(dict_ast)
print("Dict AST JIT Result:", result)  # Outputs: 80

3. Variable Environment Bindings

import ast
from jitto import run_jit

# Evaluates (a + b) * (c - d) natively on CPU hardware
ast_tree = ast.parse("(a + b) * (c - d)", mode="eval")
variables = {"a": 5, "b": 5, "c": 20, "d": 10}

result = run_jit(ast_tree, variables=variables)
print("Variable JIT Result:", result)  # Outputs: 100

Compiler Architecture

┌──────────────────────────────────────────────────────────────┐
│                    Universal AST Inputs                      │
│                                                              │
│  - Python ast.parse()  - Dataclasses (new_eval)  - Dicts     │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Universal AST Normalizer                    │
│                                                              │
│  Standardizes arbitrary AST node fields into internal nodes  │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│             3-Address Intermediate Code (IR)                 │
│                                                              │
│  Linearizes AST into LOAD_IMM, ADD, SUB, MUL & Register Alloc│
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│         Multi-Arch Machine Code Encoder (ARM64 / x86-64)      │
│                                                              │
│  Emits 64-bit CPU binary opcodes (MOVZ, ADD, SUB, MUL, RET)  │
└──────────────────────────────┬───────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────┐
│             Native RWX Memory Executor (mmap + ctypes)       │
│                                                              │
│ Executes machine bytes natively on CPU via function pointers │
└──────────────────────────────────────────────────────────────┘

Testing & Stability

jitto passes 5 comprehensive test suites comprising 22 test cases and over 1,600 continuous JIT executions:

• ARM64 & x86-64 Code Emission: Verified on macOS Apple Silicon, Intel Mac, and Linux.
• Signed 64-Bit Boundaries: Verified for negative returns (-40) and large integers (6,000,000,000).
• Multi-Threaded Concurrency: Verified across 10 concurrent threads with 500 parallel compilations.
• Deep AST Trees: Verified 30-level deep expression trees.

License

MIT