infix: A JIT-powered FFI library for C

infix is a modern, lightweight C library that lets you call any C function or create C callbacks at runtime, using simple, human-readable strings to describe the function's signature.

It's designed to be the simplest way to add a dynamic Foreign Function Interface (FFI) to your project, whether you're building a language runtime, a plugin system, or just need to call functions from a dynamically loaded library.


Key Features

• Human-Readable Signatures: Describe complex C functions with an intuitive string format (e.g., "({double, double}, int) -> *char").
• Forward & Reverse Calls: Call C functions ("forward") and create C function pointers that call back into your code ("reverse").
• Direct Marshalling API: Build high-performance language bindings where the JIT compiler calls your object-unboxing functions directly, bypassing intermediate buffers.
• Simple Integration: Add a single C file and a header directory to your project to get started. No complex dependencies.
• Type Registry: Define, reuse, and link complex, recursive, and mutually-dependent structs by name.
• Security-First Design: Hardened against vulnerabilities with Write XOR Execute (W^X) memory, guard pages, and fuzz testing.
• High Performance: A Just-in-Time (JIT) compiler generates optimized machine code trampolines, making calls nearly as fast as a direct C call after the initial setup.

Full Documentation

• Installation Guide: How to build and integrate infix.
• API Quick Reference: A complete reference for the public API.
• The FFI Cookbook: Practical, real-world examples and recipes.
• Signature Language Reference: A deep dive into the signature string format.
• Porting Guide: Instructions for adding support for a new CPU architecture or ABI.
• Contributing Guide: How to contribute to the project.

---

How It Works: A Quick Example

The heart of infix is its signature string. Here’s how you would call a simple C function:

#include <infix/infix.h>
#include <stdio.h>
 
// The C function we want to call.
int add(int a, int b) { return a + b; }
 
int main() {
    // 1. Describe the function's signature as a string.
    const char* signature = "(int, int) -> int";
 
    // 2. Create a "trampoline"—a JIT-compiled function wrapper.
    infix_forward_t* trampoline = NULL;
    infix_forward_create(&trampoline, signature, (void*)add, NULL);
    infix_cif_func cif = infix_forward_get_code(trampoline);
 
    // 3. Prepare an array of *pointers* to the arguments.
    int a = 10, b = 32;
    void* args[] = { &a, &b };
    int result;
 
    // 4. Call the function through the trampoline.
    cif(&result, args);
 
    printf("Result: %d\n", result); // Output: Result: 42
 
    // 5. Clean up.
    infix_forward_destroy(trampoline);
    return 0;
}

Creating Callbacks

infix can also generate native C function pointers that call back into your code. This is perfect for interfacing with C libraries that expect callbacks, like qsort.

#include <infix/infix.h>
#include <stdlib.h>
 
// The C handler function for our callback.
int compare_integers(const void* a, const void* b) {
    return (*(const int*)a - *(const int*)b);
}
 
void run_qsort_example() {
    // 1. Describe the callback's signature.
    const char* cmp_sig = "(*void, *void) -> int";
 
    // 2. Create a reverse trampoline.
    infix_reverse_t* context = NULL;
    infix_reverse_create_callback(&context, cmp_sig, (void*)compare_integers, NULL);
 
    // 3. Get the JIT-compiled C function pointer.
    int (*my_comparator)(const void*, const void*) = infix_reverse_get_code(context);
 
    // 4. Use the generated callback with the C library function.
    int numbers[] = { 5, 1, 4, 2, 3 };
    qsort(numbers, 5, sizeof(int), my_comparator);
    // `numbers` is now sorted: [1, 2, 3, 4, 5]
 
    infix_reverse_destroy(context);
}

High-Performance Language Bindings

If you are writing a binding for a language like Python, Perl, or Lua, infix offers a specialized direct marshalling API. This allows the JIT compiler to call your object unboxing functions ("marshallers") directly, eliminating the need to allocate intermediate C arrays.

// A mock object from a scripting language.
typedef struct { int type; union { int i; double d; } val; } PyObject;
 
// A "Scalar Marshaller" converts a language object to a raw C value.
infix_direct_value_t marshal_int(void* obj_ptr) {
    PyObject* obj = (PyObject*)obj_ptr;
    return (infix_direct_value_t){ .i64 = obj->val.i };
}
 
void run_binding_example(void* target_func) {
    // 1. Define handlers for the arguments.
    infix_direct_arg_handler_t handlers[2] = {0};
    handlers[0].scalar_marshaller = marshal_int;
    handlers[1].scalar_marshaller = marshal_int;
 
    // 2. Create an optimized trampoline.
    infix_forward_t* trampoline;
    infix_forward_create_direct(&trampoline, "(int, int) -> void", target_func, handlers, NULL);
 
    // 3. Call it directly with an array of language objects.
    PyObject* args[] = { py_obj1, py_obj2 };
 
    // The JIT code calls `marshal_int` for each arg, then calls the target.
    infix_forward_get_direct_code(trampoline)(NULL, (void**)args);
}

Getting Started

The easiest way to use infix is to add its source directly to your project.

1. Copy the src/ and include/ directories into your project.
2. Add src/infix.c to your build system's list of source files.
3. Add the include/ directory to your include paths.
4. #include <infix/infix.h> in your code.

For more advanced build options, including building as a standalone library with CMake or xmake, see the Building and Integration Guide.

Project Philosophy

infix is built on three core principles:

1. Security First: An FFI library with a JIT is a prime target for vulnerabilities. We defend against these with a multi-layered approach, including strict W^X memory, hardened integer arithmetic, and continuous fuzz testing.
2. Performance by Design: FFI overhead should be minimal. infix separates the one-time generation cost from the near-zero call-time cost, making it exceptionally fast in high-performance applications when trampolines are cached.
3. Simplicity and Portability: Platform- and ABI-specific logic is strictly isolated, making the library easy to maintain, simple to integrate, and straightforward to port to new architectures.

Platform Support

infix is rigorously tested on a wide array of operating systems, compilers, and architectures with every commit.

OS	Version	Architecture	Compiler	Status
DragonflyBSD	6.4.0	x86-64	GCC
FreeBSD	15.0	x86-64	GCC
	15.0	AArch64	GCC
	15.0	RISC-V64	GCC
	15.0	x86-64	Clang
	15.0	AArch64	Clang
	15.0	RISC-V64	Clang
macOS	Sequoia	AArch64	Clang
	Sequoia	AArch64	GCC
NetBSD	10.1	AArch64	GCC
	10.1	x86-64	GCC
OmniOS	r151054	x86-64	GCC
OpenBSD	7.8	AArch64	Clang
	7.8	AArch64	GCC
	7.8	x86-64	Clang
	7.8	x86-64	Clang
	7.8	RISC-V64	Clang
	7.8	RISC-V64	GCC
Solaris	11.4	x86-64	GCC
Ubuntu	24.04	AArch64	Clang
	24.04	AArch64	GCC
	24.04	x86-64	Clang
	24.04	x86-64	GCC
Windows	Server 2025	AArch64	Clang
	Server 2025	AArch64	GCC
	Server 2025	AArch64	MSVC
	Server 2025	x86-64	Clang
	Server 2025	x86-64	GCC
	Server 2025	x86-64	MSVC

In addition to the CI platforms tested here on Github, I can verify infix builds and passes unit tests on Android/Termux.

Licenses

To maximize usability for all, infix is dual-licensed under the [Artistic License 2.0](LICENSE-A2) and the [MIT License](LICENSE-MIT). You may choose to use the code under the terms of either license.

At your discretion, all standalone documentation (.md), explanatory text, Doxygen-style documentation blocks, comments, and code examples contained within this repository may be used, modified, and distributed under the terms of the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](LICENSE-CC). I encourage you to share and adapt the documentation for any purpose (generating an API reference website, creating tutorials, etc.), as long as you give appropriate credit.