Codon High-Performance Python Compiler

Codon is a high-performance Python implementation that compiles to native machine code without runtime overhead. It is designed for static, ahead-of-time (AOT) compilation to achieve performance comparable to C/C++.

Key performance characteristics:

• Speedups: Typically 10-100x faster than vanilla Python on a single thread.
• Multithreading: Unlike CPython, Codon supports native multithreading (no GIL), allowing for significant speedups on multicore hardware.
• Hardware Support: Designed for multicore programming, GPU acceleration, and deployment on edge or embedded devices.

Codon is a high-performance Python compiler that translates Python code into native machine code. It aims to provide C/C++ level performance (typically 10-100x speedups over CPython) while maintaining Python's syntax and ease of use.

Key technical characteristics:

• Ahead-of-Time (AOT) Compilation: Unlike JIT compilers (like Numba), Codon compiles end-to-end programs to native code.
• Native Multithreading: Supports true multithreading, unlike standard CPython.
• Static Typing: Uses novel type-checking techniques to eliminate runtime overhead.
• Garbage Collection: Uses the Boehm garbage collector.
• Extensibility: Supports a plugin infrastructure for new libraries, optimizations, and keywords.

Codon IR (CIR) is an intermediate representation that sits between the Abstract Syntax Tree (AST) and LLVM IR in the compilation process. Unlike LLVM IR, which is low-level and loses high-level semantic meaning, CIR preserves Python-like constructs (e.g., dictionary accesses, magic methods like __add__) while being much simpler and more structured than an AST. This makes it an ideal framework for writing high-level optimizations, analyses, and transformations.

Key characteristics of CIR:

• Hierarchical: Similar to ASTs but with a vastly reduced set of nodes.
• Fully Typed: All types are resolved during the AST phase; CIR does not deal with ambiguous or generic types.
• Operator Representation: Operators (like + or -) are expressed as function calls to their corresponding magic methods (e.g., __add__, __sub__).

Since LLVM IR uses Static Single Assignment (SSA) form (where variables must be assigned exactly once), Codon maps each Python variable to a stack-allocated piece of memory using the alloca instruction. This allows Python variables to be updated multiple times in the source code while remaining valid in SSA form.

; Python: x = 42
%x = alloca i64, align 8
store i64 42, i64* %x, align 8

While standard inheritance uses dynamic dispatch (resolved at runtime), Codon supports static inheritance (early binding) via the Static[BaseClass] type.

Static inheritance allows method calls to be resolved at compile time, avoiding the performance overhead of dynamic dispatch. This technique is also compatible with @tuple classes. Use this when you want to reuse a class's structure and functionality but want maximum performance and don't require runtime polymorphism.

class Foo:
    x: int
    def __init__(self, x: int):
        self.x = x
    def hello(self):
        print('Foo')

class Bar(Static[Foo]):
    def hello(self):
        print('Bar')

bar = Bar(2)
bar.hello()  # Resolved at compile time

Codon implements much of the Python standard library natively for performance. When you use import, you are accessing Codon's native implementation. If a specific module or method is not yet available natively in Codon, you can access the original CPython version by importing it from the python module.

Use import sys to use Codon's native sys module. Use from python import sys to use Python's sys module.

import sys              # uses Codon's native 'sys' module
from python import sys  # uses Python's 'sys' module

When using @codon.jit, Python types are converted to native Codon types according to these rules:

In Codon-NumPy, the ndarray type is parameterized by both the data type (dtype) and the array dimension (ndim). This means the dimension is a property of the type itself, and different dimensions result in different types (e.g., a 1-D array is a different type than a 2-D array).

Because dimensions are part of the type, they must be known at compile-time. While most NumPy functions handle this automatically, you must explicitly provide dtype and ndim when performing operations like reading arrays from disk using np.load.

import numpy as np

# The class name reveals the type parameters: ndarray[dtype, ndim]
arr = np.array([[1.1, 2.2], [3.3, 4.4]])
print(arr.__class__.__name__)  # ndarray[float,2]

arr = np.arange(10)
print(arr.__class__.__name__)  # ndarray[int,1]

# Explicitly providing dtype and ndim for loading
arr = np.load('arr.npy', dtype=float, ndim=3)

Control flow constructs (like if and while) are implemented using LLVM basic blocks.

• if statements: Create blocks for the condition, the true branch, the false branch, and an exit point. A conditional branch is generated based on the condition result.
• while loops: Create blocks for the condition, the loop body, and an exit point. The end of the body block branches back to the condition block.
• break: Becomes a direct branch to the exit block.
• continue: Becomes a direct branch to the condition block.

Representing void

You can use the Codon None type to represent C's void (e.g., for functions that return nothing or take void* pointers via cobj).

Representing Optional[T]

Codon's Optional[T] type maps to C in two ways depending on the type T:

• Reference types (classes): Optional[T] is represented as a pointer to dynamically-allocated member data, where a null pointer represents None.
• Other types: Optional[T] is represented as a C structure {bool, T}, where the boolean field indicates presence.