ffi

func CallFunction ¶

func CallFunction(
	cif *types.CallInterface,
	fn unsafe.Pointer,
	rvalue unsafe.Pointer,
	avalue []unsafe.Pointer,
) error

CallFunction executes a C function call without context support.

This is equivalent to CallFunctionContext(context.Background(), cif, fn, rvalue, avalue). For operations that need cancellation or timeout control, use CallFunctionContext instead.

Parameters:

• cif: Prepared call interface (from PrepareCallInterface)
• fn: Function pointer obtained from GetSymbol (must not be nil)
• rvalue: Pointer to buffer for return value (can be nil for void functions)
• avalue: Slice of pointers to argument values (length must match argCount from PrepareCallInterface)

Returns:

• nil on success
• ErrInvalidCallInterface if cif or fn is nil
• ErrFunctionCallFailed if the call execution fails

Example:

// Calling strlen(const char *str)
var result uintptr
str := "Hello"
err := ffi.CallFunction(
    &cif,
    strlenPtr,
    unsafe.Pointer(&result),
    []unsafe.Pointer{unsafe.Pointer(&str)},
)

For context-aware calls with timeout support, see CallFunctionContext.

func CallFunctionContext ¶

func CallFunctionContext(
	ctx context.Context,
	cif *types.CallInterface,
	fn unsafe.Pointer,
	rvalue unsafe.Pointer,
	avalue []unsafe.Pointer,
) error

CallFunctionContext executes a C function call with context support.

This function performs the actual FFI call to the C function, handling all platform-specific calling convention details automatically. It checks the context before executing to prevent starting expensive operations when the context is already cancelled or has exceeded its deadline.

Parameters:

• ctx: Context for cancellation and timeout control (use context.Background() if not needed)
• cif: Prepared call interface (from PrepareCallInterface)
• fn: Function pointer obtained from GetSymbol (must not be nil)
• rvalue: Pointer to buffer for return value (can be nil for void functions)
• avalue: Slice of pointers to argument values (length must match argCount from PrepareCallInterface)

Returns:

• nil on success
• ctx.Err() if context is cancelled or deadline exceeded before call starts
• ErrInvalidCallInterface if cif or fn is nil
• ErrFunctionCallFailed if the call execution fails

Example:

// Call with timeout
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()

var result float64
arg := 16.0
err := ffi.CallFunctionContext(
    ctx,
    &cif,
    sqrtPtr,
    unsafe.Pointer(&result),
    []unsafe.Pointer{unsafe.Pointer(&arg)},
)
if err == context.DeadlineExceeded {
    log.Println("Call timed out")
}

Note:

• Context cancellation check occurs BEFORE the call to prevent starting expensive operations when the context is already cancelled.
• Once the C function starts executing, it CANNOT be interrupted mid-flight.
• For cancellable operations, the C library itself must support cancellation.

Safety:

• All argument pointers must remain valid during the call
• Return value buffer must be large enough for the result type
• Use runtime.KeepAlive() if needed to prevent premature GC of arguments

func NewCallback ¶ added in v0.2.0

func NewCallback(fn any) uintptr

NewCallback registers a Go function as a C callback and returns a function pointer. The returned uintptr can be passed to C code as a callback function pointer.

Requirements:

• fn must be a function (not nil)
• fn can have multiple arguments of basic types (int, float, pointer, etc.)
• fn can return at most one value of basic type
• Complex types (string, slice, map, chan, interface) are not supported
• Maximum 2000 callbacks can be registered (program lifetime limit)

Memory Management:

• Callbacks are never freed (stored in global registry)
• This prevents GC from collecting callback data while C code uses it
• For applications with dynamic callback creation, consider callback pools

Usage Example:

func myCallback(x int, y float64) int {
    return x + int(y)
}

callbackPtr := ffi.NewCallback(myCallback)
// Pass callbackPtr to C code as function pointer

Using unsafe.Pointer is necessary here as we're creating a function pointer that C code can call. The pointer is obtained from the assembly trampoline table and is guaranteed to be valid for the program lifetime.

func PrepareCallInterface ¶

func PrepareCallInterface(
	cif *types.CallInterface,
	convention types.CallingConvention,
	returnType *types.TypeDescriptor,
	argTypes []*types.TypeDescriptor,
) error

PrepareCallInterface prepares a function call interface for calling a C function.

This function initializes the CallInterface structure with the necessary metadata for making FFI calls. It must be called before CallFunction.

Parameters:

• cif: Pointer to CallInterface structure to initialize (must not be nil)
• convention: Calling convention (types.DefaultCall, types.CDecl, types.StdCall, etc.)
• returnType: Type descriptor for return value (use types.VoidTypeDescriptor for void)
• argTypes: Slice of type descriptors for each argument (nil or empty slice for no arguments)

Returns:

• nil on success
• ErrInvalidCallInterface if parameters are invalid
• Other errors if type validation or platform preparation fails

Example:

var cif types.CallInterface
err := ffi.PrepareCallInterface(
    &cif,
    types.DefaultCall,
    types.Int32TypeDescriptor,
    []*types.TypeDescriptor{
        types.PointerTypeDescriptor,
        types.Int32TypeDescriptor,
    },
)

For functions with no arguments, pass nil or an empty slice for argTypes:

err := ffi.PrepareCallInterface(&cif, types.DefaultCall, types.VoidTypeDescriptor, nil)