feat: support jitclass for native codon jit class

[LeeLee26]

Proposal: Native-backed Python Classes for Codon JIT via codon.jitclass

Background

Codon already provides codon.convert as a way to expose Python classes to Codon JIT-compiled functions. This mechanism is useful for simple interoperability scenarios: a Python object can be converted into a Codon-compatible representation, passed into compiled code, and used from JIT functions.

However, codon.convert has several inherent limitations when the goal is to model Python classes as native Codon objects:

1. Object identity and lifetime are not naturally preserved

   codon.convert primarily treats Python objects as values that can be converted into Codon-side data structures. This works well for immutable or value-like objects, but it is not ideal for class instances that are expected to behave like long-lived mutable objects.

2. Mutation semantics are limited

   For Python classes with fields, users often expect operations such as:

   obj.x = 10
   obj.update()
   print(obj.x)

   to operate on the same underlying object. With conversion-based interop, field updates may not naturally map to persistent native state unless the object is explicitly reconstructed or round-tripped.

3. Methods are not represented as native class methods

   codon.convert allows converted objects to be consumed by JIT functions, but it does not make the Python class itself a native Codon class with compiled methods, constructors, and field accessors. This limits the ability to express object-oriented workloads directly in the JIT layer.

4. Performance opportunities are left on the table

   A conversion-based approach introduces boundaries between Python objects and Codon values. For class-heavy workloads, repeatedly converting objects or routing behavior through Python-level wrappers can reduce the performance benefits expected from JIT compilation.

5. The user model is less direct

   Users who write normal Python classes usually expect a decorator-based workflow where the class itself becomes compiled, rather than manually converting instances or writing separate JIT functions around them.

Because of these limitations, we propose adding first-class support for JIT-compiled classes through codon.jitclass.

---

Proposal

We propose adding codon.jitclass, a decorator that compiles a Python class into a native Codon class and exposes it through a Python proxy object.

Example:

import codon

@codon.jitclass
class Point:
    x: int
    y: int

    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

    def norm2(self) -> int:
        return self.x * self.x + self.y * self.y

p = Point(3, 4)
print(p.norm2())  # 25

p.x = 6
print(p.norm2())  # 52

The class definition is compiled by Codon JIT. Python receives a lightweight object whose data and methods are backed by a native Codon instance.

---

Key Capabilities

codon.jitclass supports:

• annotated fields,
• constructors,
• instance methods,
• field getters and setters,
• empty or method-only classes,
• explicit lifecycle management through close() and context managers.

Internally, each instance is stored in the JIT runtime using a handle. Method calls and field access are dispatched to compiled Codon wrappers.

The implementation also keeps native objects safe by rooting them in Codon’s GC while they are reachable from Python.

---

Benefits

This feature extends Codon JIT from function-level acceleration to class-level acceleration.

Compared with codon.convert, codon.jitclass provides:

• persistent native-backed objects,
• natural Python syntax for methods and fields,
• mutable state preserved across calls,
• lower conversion overhead,
• safer lifetime management for native objects,
• better support for object-oriented Python workloads.

---

Summary

codon.convert remains useful for converting Python values into Codon-compatible objects.

codon.jitclass addresses a different use case: compiling Python classes themselves into native Codon classes, while preserving a Python-friendly interface.

This makes Codon JIT more expressive and better suited for stateful, object-oriented code.

[LeeLee26]

closed

new RFC: RFC: Native-backed Python Classes for Codon JIT via codon.jitclass

PR Stack:

1. JIT: add JITCallable to wrap JIT callable functions(1/4) #813
2. JIT: add jitclass for native codon jit class(2/4) #816
3. JIT: add stale jit context detection(3/4) #814
4. JIT: support field access for codon jitclass(4/4) #817