API Reference

This page documents the public API of JustJIT.

jit

The main decorator for JIT-compiling Python functions.

jit(func=None, *, opt_level=3, vectorize=True, inline=True, parallel=False, lazy=False, mode='auto')

JIT compile a Python function for aggressive performance optimization.

Parameters:

func (callable, optional) – The function to compile. When using @jit without parentheses, this is the function being decorated.
opt_level (int) – LLVM optimization level (0-3). Default is 3 for maximum performance.
vectorize (bool) – Enable loop vectorization. Currently reserved for future use.
inline (bool) – Enable function inlining. Currently reserved for future use.
parallel (bool) – Enable parallelization. Currently reserved for future use.
lazy (bool) – Delay compilation until first call. Currently reserved for future use.
mode (str) – Compilation mode. See Compilation Modes for details.

Returns:

A JIT-compiled wrapper function.

Return type:

callable

Available modes:

'auto' - Full Python object mode (default)
'int' - 64-bit integer mode (i64)
'float' - 64-bit float mode (f64)
'bool' - Boolean mode (i1)
'int32' - 32-bit integer mode (i32)
'float32' - 32-bit float mode (f32)
'complex128' - Complex number mode ({f64, f64})
'complex64' - Single-precision complex ({f32, f32})
'ptr' - Pointer mode for array access
'vec4f' - SSE SIMD mode (<4 x f32>)
'vec8i' - AVX SIMD mode (<8 x i32>)
'optional_f64' - Nullable float64 ({i64, f64})

Usage without parentheses:

@justjit.jit
def add(a, b):
    return a + b

Usage with parameters:

@justjit.jit(mode='int', opt_level=3)
def multiply(a, b):
    return a * b

dump_ir

Retrieve the LLVM IR generated for a JIT-compiled function.

dump_ir(func)

Dump the LLVM IR for a JIT-compiled function.

Parameters:: func (callable) – A JIT-compiled function (decorated with @jit).
Returns:: The LLVM IR as a string.
Return type:: str
Raises:: ValueError – If the function is not JIT-compiled.

Example:

import justjit

@justjit.jit(mode='float')
def add(a, b):
    return a + b

# Trigger compilation
add(1.0, 2.0)

# Get the IR
ir = justjit.dump_ir(add)
print(ir)

Output:

define double @add(double %0, double %1) {
entry:
  %fadd = fadd double %0, %1
  ret double %fadd
}

inline_c

Compile C/C++ code at runtime.

inline_c(code, lang='c', captured_vars=None, include_paths=None, dump_ir=False)

Compile C or C++ code and return callable functions.

Parameters:

code (str) – C/C++ source code.
lang (str) – Language - 'c' or 'c++'.
captured_vars (dict, optional) – Variables to inject into C scope.
include_paths (list, optional) – Additional include directories.
dump_ir (bool) – Capture LLVM IR for inspection.

Returns:

Dict with 'functions' list and each function name as callable.

Return type:

dict

Raises:

RuntimeError – If Clang support not available or compilation fails.

Example:

from justjit import inline_c

result = inline_c('''
    double square(double x) { return x * x; }
''')

print(result['square'](5.0))  # Output: 25.0

dump_c_ir

Get LLVM IR from the last inline_c compilation.

dump_c_ir()

Get the LLVM IR from the last inline_c compilation.

Returns:: LLVM IR string, or None if no compilation done.
Return type:: str or None

Example:

from justjit import inline_c, dump_c_ir

inline_c('int add(int a, int b) { return a + b; }')
print(dump_c_ir())

JIT Class

The low-level JIT compiler class. Most users should use the @jit decorator instead.

class JIT

Low-level interface to the LLVM ORC JIT compiler.

__init__(): Create a new JIT compiler instance.

set_opt_level(level)

Set the LLVM optimization level.

Parameters:: level (int) – Optimization level (0-3).

get_opt_level()

Get the current LLVM optimization level.

Returns:: The optimization level.
Return type:: int

set_dump_ir(dump)

Enable or disable IR capture for debugging.

Parameters:: dump (bool) – Whether to capture IR.

get_last_ir()

Get the LLVM IR from the last compiled function.

Returns:: The IR string, or empty string if not available.
Return type:: str

compile(instructions, constants, names, globals_dict, builtins_dict, closure_cells, exception_table, name, param_count=2, total_locals=3, nlocals=3)

Compile a function to native code using the full Python object mode.

Parameters:

instructions – List of bytecode instruction dicts.
constants – List of constant values.
names – List of attribute/global names.
globals_dict – Function’s globals dictionary.
builtins_dict – Builtins dictionary.
closure_cells – List of closure cells.
exception_table – Exception table entries.
name – Function name.
param_count – Number of parameters.
total_locals – Total local variable slots.
nlocals – Number of local variables.

Returns:

True if compilation succeeded.

Return type:

bool

compile_int(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using integer mode.

compile_float(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using float mode.

compile_bool(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using bool mode.

compile_int32(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using int32 mode.

compile_float32(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using float32 mode.

compile_complex128(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using complex128 mode.

compile_complex64(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using complex64 mode.

compile_ptr(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using ptr mode.

compile_vec4f(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using vec4f mode.

compile_vec8i(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using vec8i mode.

compile_optional_f64(instructions, constants, name, param_count=2, total_locals=3): Compile a function to native code using optional_f64 mode.

compile_generator(instructions, constants, names, globals_dict, builtins_dict, closure_cells, exception_table, name, param_count, total_locals, nlocals)

Compile a generator or async function to a state machine.

Parameters:

instructions – List of bytecode instruction dicts.
constants – List of constant values.
names – List of attribute/global names.
globals_dict – Function’s globals dictionary.
builtins_dict – Builtins dictionary.
closure_cells – List of closure cells.
exception_table – Exception table entries.
name – Function name.
param_count – Number of parameters.
total_locals – Total local slots (locals + cells + freevars + stack).
nlocals – Number of local variables.

Returns:

True if compilation succeeded.

Return type:

bool

get_generator_callable(name, param_count, num_locals, gen_name, gen_qualname)

Get metadata for creating generator/coroutine objects.

Parameters:

name – Function name.
param_count – Number of parameters.
num_locals – Size of locals array.
gen_name – Generator’s __name__.
gen_qualname – Generator’s __qualname__.

Returns:

Dict with step_func_addr, num_locals, name, qualname.

Return type:

dict

get_callable(name, param_count)

Get a Python callable for a compiled function.

Parameters:

name – Function name.
param_count – Number of parameters.

Returns:

A callable that invokes the native function.

Return type:

callable

Wrapper Function Attributes

Functions decorated with @jit have additional attributes:

_jit_instance: The underlying JIT instance used for compilation.

_original_func: The original Python function before decoration.

_mode: The compilation mode used (‘int’, ‘float’, ‘auto’, etc.).

_instructions: The bytecode instructions extracted from the function.