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.
• Safe Exception Boundaries: Catch C++ and hardware exceptions (SEH) from native code to prevent host process crashes.
• 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);
}

Safe Exception Boundaries

infix can establish a "safe boundary" around FFI calls to catch C++ or SEH exceptions that occur in native code, preventing them from crashing your process.

#include <infix/infix.h>

void run_safe_example(void* crashing_func) {
    infix_forward_t* trampoline = NULL;
    // Create a "safe" trampoline.
    infix_forward_create_safe(&trampoline, "() -> void", crashing_func, NULL);

    infix_cif_func cif = infix_forward_get_code(trampoline);
    
    // Call the function. If it throws a C++ exception, it will be caught.
    cif(NULL, NULL);

    // Check for exceptions.
    infix_error_details_t err = infix_get_last_error();
    if (err.code == INFIX_CODE_NATIVE_EXCEPTION) {
        printf("Caught an exception from native code: %s\n", err.message);
    }

    infix_forward_destroy(trampoline);
}

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.

Note: If you are linking against infix as a shared library (DLL) on Windows, you must define INFIX_USING_DLL in your project settings. See the Installation Guide for details.

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
	Sequoia	x86-64	GCC
	Sequoia	x86-64	Clang
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
	24.04	RISC-V64	Clang
	24.04	RISC-V64	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 and the MIT License. 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). 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.