Binding Methods in Zig

March 26, 2025 • 27 min read • by renerocksai

- The Challenge in Zig
- Exploring Initial Approaches
  - Attempt 1: The Runtime Closure Misconception
  - Attempt 2: A Generic Wrapper Struct (Explicit Bundling)
  - Attempt 3: The Nested Interface and @fieldParentPtr
- The Solution: Decoupling Binding and Interface
- Relation to Standard Zig Interfaces (VTable Pattern)
  - Trade-offs
  - Conclusion

In object-oriented languages like Python, passing instance methods around as callbacks is incredibly convenient. The language handles the complexity of ensuring the method knows which instance (self) it belongs to. Consider a simple event handler:

class Greeter:
    def __init__(self, name):
        self.name = name

    def say_hello(self):
        # This method needs 'self' (the instance context)
        print(f"Hello from {self.name}!")

# Some hypothetical API function that takes a callback
def register_callback(callback_func):
    print("Registering callback...")
    # Later, the API invokes the callback
    callback_func()

# --- Usage ---
greeter_instance = Greeter("Alice")

# We can pass the *bound method* directly!
# Python implicitly captures 'self' (greeter_instance)
register_callback(greeter_instance.say_hello)

# Output:
# Registering callback...
# Hello from Alice!

The “bound method” greeter_instance.say_hello is more than just a function pointer; it’s an object packaging the function and the instance (greeter_instance). When invoked, Python ensures say_hello receives the correct self.

The Challenge in Zig

Zig, prioritizing explicitness and control, lacks this implicit binding. A “method” is typically just a function taking a pointer to a struct as its first argument (self). This creates a mismatch when interacting with APIs expecting simple function pointers.

Imagine a Zig API wanting a simple callback:

const std = @import("std");

// Hypothetical API expecting a simple function pointer
fn registerCallback(callback_fn: *const fn() void) void {
    std.debug.print("Registering Zig callback...\n", .{});
    callback_fn();
}

const Greeter = struct {
    name: []const u8,

    // Needs '*Greeter' as the first argument
    pub fn sayHello(self: *const Greeter) void {
        std.debug.print("Hello from {s}!\n", .{self.name});
    }
};

// --- Attempted Usage ---
test "direct callback fails" {
    var greeter_instance : Greeter = .{.name = "Alice" };

    // This WON'T compile!
    // registerCallback(&Greeter.sayHello);
    // Error: Expected '*const fn () void', found '*const fn (*const main.Greeter) void'
}

The API expects fn() void, but Greeter.sayHello requires a *const Greeter context. How do we bridge this gap and supply the necessary self pointer?

Exploring Initial Approaches

Before arriving at the final CallbackInterface pattern, let’s walk through the thought process. How might we tackle this problem in Zig initially, and what challenges arise? Understanding these steps is key to appreciating the final design.

The Core Problem Recap: An API expects a simple function pointer like *const fn(ArgType) void. Our goal is to pass something that acts like an instance method, effectively fn(self: *MyInstance, ArgType) void, giving the callback access to instance data (self).

Attempt 1: The Runtime Closure Misconception

A common pattern in other languages involves functions or methods “closing over” variables from their surrounding scope. Can we leverage this in Zig? Let’s try defining a struct with a method inside a function, attempting to access that function’s arguments or local variables that hold runtime state:

const std = @import("std");

// --- The Goal ---
// An instance type with a method needing 'self'
const Greeter = struct {
    name: []const u8,
    pub fn sayHello(self: *const Greeter) void {
        std.debug.print("Hello from {s}!\n", .{self.name});
    }
};
// An API expecting a simple callback without context
fn registerCallback(callback_fn: *const fn () void) void {
    std.debug.print("Registering callback...\n", .{});
    callback_fn();
}

// --- The Attempt ---
// A function that takes the instance as a RUNTIME argument
fn setupAndRegisterCallback(instance: *const Greeter) void {
    // Define a struct locally inside the function
    const LocalGreeterWrapper = struct {
        // Attempt to define a method that uses the outer function's 'instance' argument
        fn cb() void {
            // PROBLEM: Try to access 'instance' from setupAndRegisterCallback
            instance.sayHello(); // This line causes the error
        }
    };

    // Try to pass the nested method to the API
    registerCallback(LocalGreeterWrapper.cb);
}

test "Local Struct Method Access Runtime State" {
    const greeter_instance = Greeter{ .name = "Alice" };
    // Pass the runtime instance pointer to the setup function
    setupAndRegisterCallback(&greeter_instance);
}

This attempt fails to compile with a clear error:

error: 'instance' not accessible from inner function
            instance.sayHello();
            ^~~~~~~~
note: crossed function definition here
        fn cb() void {
        ^~~~~~~~~~~~

Why it Fails (Runtime vs. Compile-Time):

The error message “'instance' not accessible from inner function” highlights a key aspect of Zig: functions and methods do not form runtime closures.

The instance parameter passed to setupAndRegisterCallback is a runtime value (a pointer whose specific address is known only during execution).
The method LocalGreeterWrapper.cb, although defined textually within setupAndRegisterCallback, is compiled into fixed code. This code has no built-in mechanism to dynamically access runtime variables or parameters (like instance) belonging to the specific stack frame of an outer runtime function (setupAndRegisterCallback) that might be active when cb is invoked.

Important Distinction: Compile-Time Context is Accessible

Above limitation applies specifically to capturing runtime state from outer runtime scopes. If an outer scope involves compile-time known values (e.g., function parameters in a comptime function, const values evaluated at compile time), methods of nested structs can access those. This is because the compiler can embed or directly reference these known values when generating the code for the nested methods.

// Example: Accessing comptime context
fn makeStructWithComptimeData(comptime prefix: []const u8) type {
    const suffix = "-end"; // Compile-time known const
    return struct {
        fn getMessage() []const u8 {
            // OK: Accessing 'comptime prefix' and 'const suffix'
            return prefix ++ suffix;
        }
    };
}
test "comptime context access" {
    const S = makeStructWithComptimeData("start");
    try std.testing.expectEqualStrings("start-end", S.getMessage());
}

However, accessing compile-time context doesn’t solve our core callback problem. The callback needs access to the specific runtime instance data passed into setupAndRegisterCallback. Zig requires an explicit mechanism to bundle this runtime context with the function pointer, rather than relying on implicit runtime closures.

Attempt 2: A Generic Wrapper Struct (Explicit Bundling)

Let’s create a dedicated struct to hold the two essential pieces of information: the pointer to the specific instance (*Instance) and a pointer to the code of the instance method we want to call (*const MethodFunc).

fn BindAttempt2(Instance: type, MethodFunc: type) type {
    // Assume MethodFunc is the type of the instance method, e.g., fn(*Instance, Args...)
    return struct {
        instance_ptr: *Instance,
        method_ptr: *const MethodFunc,

        // ... Now what? ...
        pub fn init(inst: *Instance, meth: *const MethodFunc) @This() {
             return .{ .instance_ptr = inst, .method_ptr = meth };
        }
    };
}

// Usage:
// var greeter_instance = Greeter{.name = "Alice"};
// var binding = BindAttempt2(Greeter, @TypeOf(&Greeter.sayHello)).init(&greeter_instance, &Greeter.sayHello);

This struct successfully stores the context (binding.instance_ptr) and the function (binding.method_ptr). But we’re still stuck on the original problem: how do we give the API (expecting *const fn() void) something it can actually call? We can’t just give it a pointer to the binding struct. We need a plain function pointer that somehow uses the data inside binding.

Attempt 3: The Nested Interface and `@fieldParentPtr`

This approach tries to leverage more of Zig’s specific features. The idea is to embed a small “interface” struct within our main wrapper (BoundFunction). The API would interact with a pointer to this nested interface. We then need the function called via this interface pointer to somehow retrieve the context (the instance and method pointers) stored in the parent BoundFunction struct.

Zig provides a builtin function, @fieldParentPtr, designed for similar scenarios. Given a pointer to a field within a struct, along with the parent struct type and the field name, @fieldParentPtr calculates the memory address of the beginning of that parent struct instance.

The structure would look something like this conceptually:

The main BoundFunction struct holds instance and method pointers.
A nested BindInterface struct is defined inside BoundFunction. It contains a single call function pointer field.
This call pointer points to a static helper function (let’s call it callHelper) also defined within BoundFunction.
Crucially, callHelper would be designed to take a pointer to the BindInterface field itself as its first argument.
Inside callHelper, @fieldParentPtr would be used: “Given this pointer to the interface_ field, find the BoundFunction that contains it.”
Once callHelper retrieves the BoundFunction pointer (self), it can access self.instance and self.method to perform the actual call.

/// Helper function that returns a function type with ArgType prepended to the
/// function's args.
/// Example:
///     Func    = fn(usize) void
///     ArgType = *Instance
///     --------------------------
///     Result  = fn(*Instance, usize) void
fn PrependFnArg(Func: type, ArgType: type) type {
    const fn_info = @typeInfo(Func);
    if (fn_info != .@"fn") @compileError("First argument must be a function type");

    comptime var new_params: [fn_info.@"fn".params.len + 1]std.builtin.Type.Fn.Param = undefined;
    new_params[0] = .{ .is_generic = false, .is_noalias = false, .type = ArgType };
    for (fn_info.@"fn".params, 0..) |param, i| {
        new_params[i + 1] = param;
    }

    return @Type(.{
        .@"fn" = .{
            .calling_convention = fn_info.@"fn".calling_convention,
            .is_generic = fn_info.@"fn".is_generic,
            .is_var_args = fn_info.@"fn".is_var_args,
            .return_type = fn_info.@"fn".return_type,
            .params = &new_params,
        },
    });
}

// Conceptual sketch for Attempt 3
pub fn BindAttempt3(Instance: type, Func: type) type { // Func = fn(Args...)
    // ... type calculations ...
    const InstanceMethod = PrependFnArg(Func, *Instance); // fn(*Inst, Args...)
    const FuncArgs = std.meta.ArgsTuple(Func); // Args

    // Define the nested interface struct
    const BindInterface = struct {
        call: *const fn (*const BindInterface, Args) ReturnType,
    };

    // Define the main wrapper struct
    return struct {
        instance: *Instance,
        method: *const InstanceMethod,
        interface_: BindInterface, // Embed the interface

        pub const BoundFunction = @This();

        // The helper function pointed to by BindInterface.call
        fn callHelper(interface_ptr: *const BindInterface, ) ReturnType {
            // Use @fieldParentPtr to get 'self' (the BoundFunction instance)
            const self: *const BoundFunction = @alignCast(
                @fieldParentPtr(BoundFunction, "interface_", interface_ptr)
            );

            // Now use self.instance and self.method to call the real method
            // ... call self.method ...
        }

        pub fn init(...) BoundFunction {
            return .{
                // .interface = ...,
                // .method = ...,
                .interface_ = .{ .call = &callHelper },
            };
        }
        // ...
    };
}

Addressing Hurdles within Attempt 3:

Argument Passing: The function pointer stored in call needs a concrete signature. We can’t define InterfaceCallFnType using anytype for the arguments because function pointers need concrete types. So we use std.meta.ArgsTuple to package the original function arguments.
The Polymorphism Problem (The Showstopper): This @fieldParentPtr approach, while functional for binding a single instance and cleverly retrieving context, hits a major wall when we desire polymorphism. Consider binding methods from a Person and a Dog that share the same callback signature Func:
- Bind(Person, Func) generates a unique wrapper struct type (BoundPerson) containing BoundPerson.BindInterface.
- Bind(Dog, Func) generates another unique wrapper type (BoundDog) containing BoundDog.BindInterface.
- Even if BoundPerson.BindInterface and BoundDog.BindInterface look identical structurally, Zig considers them distinct types because they are nested within different parent types (BoundPerson vs. BoundDog).
- Furthermore, the callHelper functions within each are subtly different, as their @fieldParentPtr calculation depends on the specific parent type.
- Result: You cannot store instances of BoundPerson.BindInterface and BoundDog.BindInterface in a common list (e.g., []SomeCommonInterfaceType) or treat them uniformly. The interface type itself remains tied to the specific Instance used in Bind.

Moving Forward:

The limitation of this approach highlights that for true polymorphism based on the callback signature alone, the interface type must be decoupled from the specific Instance being bound. It cannot be nested within the Bind result if we rely on @fieldParentPtr for context retrieval. This necessitates a different strategy for managing the context, leading us to the final solution involving type erasure (anyopaque) and an external interface definition.

To achieve true polymorphism where interfaces derived from different Instance types (but the same Func signature) are themselves the same type, we must:

Define the interface type outside the Bind function’s result.
Make the interface type depend only on the Func signature.
Find a different way to provide the necessary context (BoundFunction pointer) to the function called via the interface – this leads us to type erasure using anyopaque.

The Solution: Decoupling Binding and Interface

The robust solution involves two distinct components working together:

Bind(Instance, Func) type: A generic function that creates a struct (BoundFunction) responsible solely for capturing the context. It stores the *Instance pointer and the *const InstanceMethod pointer.
CallbackInterface(Func) type: A generic function that creates the interface type based purely on the original function signature Func. This interface type is the contract that API authors will use. It leverages type erasure (anyopaque) to hold the context generically.

The key shift in thinking: Instead of an API asking for a raw function pointer *const MyFuncType, it will now ask for an instance of CallbackInterface(MyFuncType).

// API Definition Change:
// Old:
fn processItems(items: []Item, callback: *const fn(Item) void) void
// New:
fn processItems(items: []Item, callback: CallbackInterface(fn(Item) void)) void

Let’s look at the code:

1. The CallbackInterface (External and Generic)

// Creates a type-erased callback interface type for a given function signature Func.
pub fn CallbackInterface(comptime Func: type) type {
    const func_info = @typeInfo(Func);
    if (func_info != .@"fn") @compileError("CallbackInterface expects a function type");
    if (func_info.@"fn".is_generic) @compileError("CallbackInterface does not support generic functions");
    if (func_info.@"fn".is_var_args) @compileError("CallbackInterface does not support var_args functions");

    const ArgsTupleType = std.meta.ArgsTuple(Func); // e.g., struct{"0": []const u8}
    const ReturnType = func_info.@"fn".return_type.?; // Allow void
    // The required signature for our internal trampoline function
    const FnPtrType = *const fn (ctx: ?*const anyopaque, args: ArgsTupleType) ReturnType;

    return struct {
        // Stores the BoundFunction (or any context) as an opaque const pointer
        ctx: ?*const anyopaque,
        // Stores the pointer to the trampoline function
        callFn: FnPtrType,

        pub const Interface = @This();

        // The public method API consumers call
        pub fn call(self: Interface, args: ArgsTupleType) ReturnType {
            if (self.ctx == null) @panic("Called uninitialized CallbackInterface");
            // Simply delegate to the trampoline
            if (ReturnType == void) {
                self.callFn(self.ctx, args);
            } else {
                return self.callFn(self.ctx, args);
            }
        }
    };
}

This defines a struct whose type only depends on the Func signature.
ctx: ?*const anyopaque: This is the type erasure part. It holds a const pointer to anything. We’ll store our BoundFunction pointer here.
callFn: FnPtrType: A function pointer expecting the opaque context and the original function’s arguments packaged in a tuple (ArgsTupleType). This will point to our “trampoline” function.
call(): The method users of the interface call. It simply forwards the call to callFn, passing the stored context and arguments. Notice the caller provides arguments as a tuple literal (e.g., .{"arg1", "arg2"}).

Trampoline Functions

A trampoline function is generally an intermediary piece of code that performs some setup or transition (like changing stack frames, adjusting calling conventions, or handling type erasure) before transferring control to another target function, often used to bridge incompatible calling mechanisms or manage complex control flow like deep recursion without blowing the stack.

In our context, it is a small intermediate function whose job is to receive generic or type-erased arguments (like an anyopaque context pointer), perform necessary type casting or setup (like casting the context back to its real type), and then “bounce” or delegate the call to the actual target function with the correctly typed arguments.

2. The Bind Function (Capturing Context)

// Creates a struct that binds an instance to a method matching Func's signature,
// and provides a way to get a type-erased CallbackInterface.
pub fn Bind(Instance: type, Func: type) type {
    const func_info = @typeInfo(Func);
    if (func_info != .@"fn") @compileError("Bind expects a function type as second parameter");
    if (func_info.@"fn".is_generic) @compileError("Binding generic functions is not supported");
    if (func_info.@"fn".is_var_args) @compileError("Binding var_args functions is not currently supported");

    const ReturnType = func_info.@"fn".return_type.?;
    const OriginalParams = func_info.@"fn".params; // Needed for comptime loops
    const ArgsTupleType = std.meta.ArgsTuple(Func);
    const InstanceMethod = PrependFnArg(Func, *Instance);
    const InterfaceType = CallbackInterface(Func);

    return struct {
        instance: *Instance,
        method: *const InstanceMethod,
        pub const BoundFunction = @This();

        // Trampoline function using runtime tuple construction
        fn callDetached(ctx: ?*const anyopaque, args: ArgsTupleType) ReturnType {
            if (ctx == null) @panic("callDetached called with null context");
            const self: *const BoundFunction = @ptrCast(@alignCast(ctx.?));

            // 1. Define the tuple type needed for the call: .{*Instance, OriginalArgs...}
            const CallArgsTupleType = comptime T: {
                var tuple_fields: [OriginalParams.len + 1]std.builtin.Type.StructField = undefined;
                // Field 0: *Instance type
                tuple_fields[0] = .{
                    .name = "0",
                    .type = @TypeOf(self.instance),
                    .default_value_ptr = null,
                    .is_comptime = false,
                    .alignment = 0,
                };
                // Fields 1..N: Original argument types (use ArgsTupleType fields)
                for (std.meta.fields(ArgsTupleType), 0..) |field, i| {
                    tuple_fields[i + 1] = .{
                        .name = std.fmt.comptimePrint("{d}", .{i + 1}),
                        .type = field.type,
                        .default_value_ptr = null,
                        .is_comptime = false,
                        .alignment = 0,
                    };
                }
                break :T @Type(.{ .@"struct" = .{
                    .layout = .auto,
                    .fields = &tuple_fields,
                    .decls = &.{},
                    .is_tuple = true,
                } });
            };

            // 2. Create and populate the tuple at runtime
            var call_args_tuple: CallArgsTupleType = undefined;
            @field(call_args_tuple, "0") = self.instance; // Set the instance pointer

            // Copy original args from 'args' tuple to 'call_args_tuple'
            comptime var i = 0;
            inline while (i < OriginalParams.len) : (i += 1) {
                const src_field_name = comptime std.fmt.comptimePrint("{}", .{i});
                const dest_field_name = comptime std.fmt.comptimePrint("{}", .{i + 1});
                @field(call_args_tuple, dest_field_name) = @field(args, src_field_name);
            }

            // 3. Perform the call using the populated tuple
            if (ReturnType == void) {
                @call(.auto, self.method, call_args_tuple);
            } else {
                return @call(.auto, self.method, call_args_tuple);
            }
        }

        pub fn interface(self: *const BoundFunction) InterfaceType {
            return .{ .ctx = @ptrCast(self), .callFn = &callDetached };
        }

        // Direct call convenience method using runtime tuple construction
        pub fn call(self: *const BoundFunction, args: anytype) ReturnType {
            // 1. Verify 'args' is the correct ArgsTupleType
            // (This check could be more robust if needed)
            if (@TypeOf(args) != ArgsTupleType) {
                // Attempt reasonable check for tuple literal compatibility
                if (@typeInfo(@TypeOf(args)) != .@"struct" or !@typeInfo(@TypeOf(args)).@"struct".is_tuple) {
                    @compileError(std.fmt.comptimePrint(
                        "Direct .call expects arguments as a tuple literal compatible with {}, found type {}",
                        .{ ArgsTupleType, @TypeOf(args) },
                    ));
                }
                // Further check field count/types if necessary
                if (std.meta.fields(@TypeOf(args)).len != OriginalParams.len) {
                    @compileError(std.fmt.comptimePrint(
                        "Direct .call tuple literal has wrong number of arguments (expected {}, got {}) for {}",
                        .{ OriginalParams.len, std.meta.fields(@TypeOf(args)).len, ArgsTupleType },
                    ));
                }
                // Could add type checks per field here too
            }

            // 2. Define the tuple type needed for the call: .{*Instance, OriginalArgs...}
            const CallArgsTupleType = comptime T: {
                var tuple_fields: [OriginalParams.len + 1]std.builtin.Type.StructField = undefined;
                tuple_fields[0] = .{
                    .name = "0",
                    .type = @TypeOf(self.instance),
                    .default_value_ptr = null,
                    .is_comptime = false,
                    .alignment = 0,
                };
                for (std.meta.fields(ArgsTupleType), 0..) |field, i| {
                    tuple_fields[i + 1] = .{
                        .name = std.fmt.comptimePrint("{d}", .{i + 1}),
                        .type = field.type,
                        .default_value_ptr = null,
                        .is_comptime = false,
                        .alignment = 0,
                    };
                }
                break :T @Type(.{ .@"struct" = .{
                    .layout = .auto,
                    .fields = &tuple_fields,
                    .decls = &.{},
                    .is_tuple = true,
                } });
            };

            // 3. Create and populate the tuple at runtime
            var call_args_tuple: CallArgsTupleType = undefined;
            @field(call_args_tuple, "0") = self.instance;

            comptime var i = 0;
            inline while (i < OriginalParams.len) : (i += 1) {
                const field_name = comptime std.fmt.comptimePrint("{}", .{i});
                // Check if field exists in args (useful for struct literals, less for tuples)
                // For tuple literals, direct access should work if type check passed.
                // if (@hasField(@TypeOf(args), field_name)) { ... }
                const dest_field_name = comptime std.fmt.comptimePrint("{}", .{i + 1});
                @field(call_args_tuple, dest_field_name) = @field(args, field_name);
            }

            // 4. Perform the call using the populated tuple
            if (ReturnType == void) {
                @call(.auto, self.method, call_args_tuple);
            } else {
                return @call(.auto, self.method, call_args_tuple);
            }
        }

        pub fn init(instance_: *Instance, method_: *const InstanceMethod) BoundFunction {
            return .{ .instance = instance_, .method = method_ };
        }
    };
}

/// Helper function that returns a function type with ArgType prepended to the
/// function's args.
/// Example:
///     Func    = fn(usize) void
///     ArgType = *Instance
///     --------------------------
///     Result  = fn(*Instance, usize) void
fn PrependFnArg(Func: type, ArgType: type) type {
    const fn_info = @typeInfo(Func);
    if (fn_info != .@"fn") @compileError("First argument must be a function type");

    comptime var new_params: [fn_info.@"fn".params.len + 1]std.builtin.Type.Fn.Param = undefined;
    new_params[0] = .{ .is_generic = false, .is_noalias = false, .type = ArgType };
    for (fn_info.@"fn".params, 0..) |param, i| {
        new_params[i + 1] = param;
    }

    return @Type(.{
        .@"fn" = .{
            .calling_convention = fn_info.@"fn".calling_convention,
            .is_generic = fn_info.@"fn".is_generic,
            .is_var_args = fn_info.@"fn".is_var_args,
            .return_type = fn_info.@"fn".return_type,
            .params = &new_params,
        },
    });
}

Bind returns a BoundFunction struct storing instance and method.
callDetached: This is the crucial trampoline function.
- It matches the FnPtrType signature required by CallbackInterface.
- It receives the anyopaque context and casts it back to *const BoundFunction. This is safe because we know by construction that ctx will always hold a pointer to a BoundFunction when created via interface().
- It retrieves the instance and method pointers from the recovered self.
- It constructs the final argument tuple (.{self.instance, original_args...}) needed by the actual method.
- It uses @call to invoke the original method.
interface(): This method is called on a BoundFunction instance. It creates and returns a CallbackInterface struct, populating ctx with a type-erased pointer to itself and callFn with the address of the callDetached trampoline.

3. Putting it Together: Polymorphic Callbacks

Now, our Person and Dog example works beautifully, demonstrating polymorphism:

test "BindInterface Polymorphism (External)" {
    const Person = struct {
        name: []const u8,
        _buf: [1024]u8 = undefined,
        pub fn speak(self: *@This(), message: []const u8) ![]const u8 {
            return std.fmt.bufPrint(&self._buf, "{s} says: >>{s}!<<\n", .{ self.name, message });
        }
    };

    const Dog = struct {
        name: []const u8,
        _buf: [1024]u8 = undefined,
        pub fn bark(self: *@This(), message: []const u8) ![]const u8 {
            return std.fmt.bufPrint(&self._buf, "{s} barks: >>{s}!<<\n", .{ self.name, message });
        }
    };

    // The common callback signature
    const CallBack = fn ([]const u8) anyerror![]const u8;
    // The SINGLE interface type derived from CallBack
    const CbInterface = CallbackInterface(CallBack);

    var alice: Person = .{ .name = "Alice" };
    const bound_alice = Bind(Person, CallBack).init(&alice, &Person.speak);
    // alice_interface has type CbInterface
    const alice_interface = bound_alice.interface();

    var bob: Dog = .{ .name = "Bob" };
    const bound_bob = Bind(Dog, CallBack).init(&bob, &Dog.bark);
    // bob_interface ALSO has type CbInterface
    const bob_interface = bound_bob.interface();

    // We can store them in the same array!
    const interfaces = [_]CbInterface{ alice_interface, bob_interface };
    var results: [2][]const u8 = undefined;

    // The calling code uses the simple .call(args_tuple) method
    for (interfaces, 0..) |iface, i| {
        results[i] = try iface.call(.{"Test"});
    }

    try testing.expectEqualStrings("Alice says: >>Test!<<\n", results[0]);
    try testing.expectEqualStrings("Bob barks: >>Test!<<\n", results[1]);
}

Because CallbackInterface(CallBack) produces the same type regardless of whether the underlying context is a Person or a Dog, we can treat them polymorphically.

Looking back, this approach is still not as painless as Python’s bound methods, as it uses interface instances as opposed to function pointers, yet it’s the closest I could come up with so far.

Phew, that was a lot! I know. Thanks for making it this far 😊!

Relation to Standard Zig Interfaces (VTable Pattern)

Experienced Zig developers might recognize similarities between our CallbackInterface and the common pattern used for implementing interfaces like std.mem.Allocator. Let’s clarify the relationship.

The Standard VTable/anyopaque Interface Pattern

The typical way to create a dynamic interface in Zig involves:

The Interface Struct: Defines the contract, usually containing ptr: *anyopaque for context and function pointers (often in a VTable struct) for a fixed set of operations:

ptr: *anyopaque,         // type-erased
vtable: *const VTable,

pub const VTable = struct {
    // type-erased--------v
    alloc: *const fn (*anyopaque, len: usize, alignment: Alignment, ret_addr: usize) ?[*]u8,
    free:  *const fn (*anyopaque, memory: []u8, alignment: Alignment, ret_addr: usize) void,
    // ...

The Implementation: A concrete type providing logic for the interface methods.
Type Erasure and Casting: The implementation pointer is cast to *anyopaque on interface creation and cast back within the actual implementation functions or trampoline functions, using @ptrCast/@alignCast.
Trampolines: Functions associated with the implementation (or generated via a generic Interface.init) that handle the casting and delegate to the actual implementation logic.

How Our CallbackInterface + Bind Pattern Compares

Our approach leverages the same fundamental principles but is specialized:

Shared Principles: Type erasure (anyopaque), function pointers, trampolines, and enabling polymorphism.
Key Differences & Specialization:
- Interface Definition (Fixed Set vs. Arbitrary Single Signature): Standard interfaces (Writer, Allocator) define a fixed set of operations. Our CallbackInterface(Func) generates an interface type tailored dynamically to one specific, arbitrary function signature Func. It allows binding any function signature as a single-action callback interface, not just those belonging to a pre-defined suite.
- Context (ctx vs. ptr): Standard interfaces usually store a pointer directly to the implementation (*File). Our ctx points to the intermediate BoundFunction struct, which then holds the target instance and method.
- Trampoline Location & Knowledge: Our callDetached trampoline is part of the Bind mechanism, specifically knowing how to unpack the BoundFunction context. Standard trampolines are tied to the implementation type.
- Purpose: The standard pattern is general-purpose dynamic dispatch for a known set of operations. Ours is a specific solution for adapting any single instance method for callback APIs expecting a matching signature (minus self), enabling polymorphism based on the callback signature itself.

When to Use Which?

Standard VTable Interface: For general-purpose interfaces defining a contract with multiple, known operations (like std.io.Writer, std.mem.Allocator).
CallbackInterface + Bind: Specifically when adapting a single instance method as a callback for an API expecting a function pointer matching that method’s signature (minus self), especially when needing polymorphism based on that signature across different instance types.

Trade-offs

Type Erasure: We use anyopaque, requiring a runtime cast inside callDetached (though safe by construction).
Indirection: An extra function call via callFn (usually negligible).
API Design: Requires APIs to adopt the CallbackInterface(Func) pattern.
Caller Syntax: Interface callers use .call(.{arg1, arg2}) with tuple literals.

Conclusion

By decoupling context capture (Bind) from a generic, signature-driven interface (CallbackInterface) using type erasure and a trampoline function (callDetached), we achieve a powerful and flexible callback mechanism in Zig. This pattern provides a type-safe way to bind instance methods for APIs expecting simpler function pointers, enabling Python-like convenience and polymorphic behavior based on the callback signature, all while adhering to Zig’s philosophy of explicitness. It bridges the gap between instance-oriented methods and function-pointer-based APIs, with the caveat that those APIs need to be aware of it (using CallbackInterface(Func)) — which is fine if the API author is you (me, in my case). 😊

← You Need a Sheet of Paper or Back to the Homepage

@renerocksai

Binding Methods in Zig

Table of Contents

The Challenge in Zig

Exploring Initial Approaches

Attempt 1: The Runtime Closure Misconception

Important Distinction: Compile-Time Context is Accessible

Attempt 2: A Generic Wrapper Struct (Explicit Bundling)

Attempt 3: The Nested Interface and `@fieldParentPtr`

The Solution: Decoupling Binding and Interface

Trampoline Functions

Relation to Standard Zig Interfaces (VTable Pattern)

Trade-offs

Conclusion

@renerocksai

Binding Methods in Zig

Table of Contents

The Challenge in Zig

Exploring Initial Approaches

Attempt 1: The Runtime Closure Misconception

Important Distinction: Compile-Time Context is Accessible

Attempt 2: A Generic Wrapper Struct (Explicit Bundling)

Attempt 3: The Nested Interface and @fieldParentPtr

The Solution: Decoupling Binding and Interface

Trampoline Functions

Relation to Standard Zig Interfaces (VTable Pattern)

Trade-offs

Conclusion

Attempt 3: The Nested Interface and `@fieldParentPtr`