Support Python callbacks in cffi backend

Author: b-long

.github/workflows/ci.yml

@@ -137,8 +137,9 @@ jobs:
       run: go build -v ./...
 
     # The skipped tests use features the cffi backend does not support yet:
-    # Python callback arguments (TestBindFuncs), and complex numbers as a
-    # slice element rather than a plain function arg/return (TestBuiltinSlices;
-    # see genFuncComplexCFFI in gen_func.go for the arg/return case, which works).
+    # Python callbacks that take an interface{} or return a value
+    # (TestBindFuncs; see cffi_callback.go for the ones that work), and complex
+    # numbers as a slice element rather than a plain function arg/return
+    # (TestBuiltinSlices; see genFuncComplexCFFI in gen_func.go for the case that works).
     - name: Test
       run: go test -v -skip '^(TestBindFuncs|TestBuiltinSlices)$' ./...

SUPPORT_MATRIX.md

@@ -6,6 +6,7 @@ don't modify manually.
 Feature |py3
 --- | ---
 _examples/arrays | yes
+_examples/callbacks | yes
 _examples/cgo | yes
 _examples/consts | yes
 _examples/cstrings | yes

_examples/callbacks/callbacks.go

@@ -0,0 +1,55 @@
+// Copyright 2026 The go-python Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package callbacks has Go functions that take Python callables, and call
+// them before returning.
+package callbacks
+
+import (
+	"fmt"
+	"sync"
+)
+
+// Each calls fun for i in 0..n-1, with a label made from i.
+func Each(n int, fun func(i int, label string)) {
+	for i := 0; i < n; i++ {
+		fun(i, fmt.Sprintf("item-%d", i))
+	}
+}
+
+// Mixed calls fun with a bool, a float and an unsigned integer.
+func Mixed(fun func(on bool, x float64, u uint8)) {
+	fun(true, 1.5, 200)
+	fun(false, -2.25, 7)
+}
+
+// Twice calls fun, which takes no arguments, two times.
+func Twice(fun func()) {
+	fun()
+	fun()
+}
+
+// Counter counts how many times it has been visited.
+type Counter struct {
+	N int
+}
+
+// Visit calls fun with the counter itself, which arrives as a handle.
+func (c *Counter) Visit(times int, fun func(c *Counter, n int)) {
+	for i := 0; i < times; i++ {
+		c.N++
+		fun(c, c.N)
+	}
+}
+
+// InGoroutine calls fun from another goroutine, and waits for it.
+func InGoroutine(fun func(i int)) {
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		fun(7)
+	}()
+	wg.Wait()
+}

_examples/callbacks/test.py

@@ -0,0 +1,65 @@
+# Copyright 2026 The go-python Authors.  All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
+from __future__ import print_function
+
+import io
+import sys
+
+import callbacks
+
+print("--- Each: int and string arguments")
+callbacks.Each(3, lambda i, label: print("each:", i, label))
+
+print("--- Mixed: bool, float and uint8 arguments")
+# bool() because the pybindgen backend passes a bool as 1 or 0
+callbacks.Mixed(lambda on, x, u: print("mixed:", bool(on), x, u))
+
+print("--- Twice: no arguments")
+calls = []
+callbacks.Twice(lambda: calls.append(1))
+print("twice:", len(calls))
+
+print("--- Counter.Visit: a Go struct arrives as a handle")
+c = callbacks.Counter()
+
+def visit(handle, n):
+    seen = callbacks.Counter(handle=handle)
+    print("visit:", n, seen.N)
+
+c.Visit(2, visit)
+print("counter:", c.N)
+
+print("--- a bound method")
+
+class Box(object):
+    def __init__(self):
+        self.items = []
+
+    def add(self, i, label):
+        self.items.append((i, label))
+
+box = Box()
+callbacks.Each(2, box.add)
+print("box:", box.items)
+
+print("--- called from another goroutine")
+callbacks.InGoroutine(lambda i: print("goroutine:", i))
+
+print("--- an exception in a callback is reported, and Go carries on")
+seen = []
+
+def boom(i, label):
+    seen.append(i)
+    raise ValueError("boom %d" % i)
+
+stderr, sys.stderr = sys.stderr, io.StringIO()
+try:
+    callbacks.Each(3, boom)
+    reported = sys.stderr.getvalue()
+finally:
+    sys.stderr = stderr
+print("calls:", len(seen), "reported:", reported.count("ValueError: boom"))
+
+print("OK")

bind/cffi.go

@@ -38,7 +38,8 @@ func (g *pyGen) goSetError(kind, msg string) string {
 }
 
 // same argument positions as goPreamble: 1 = name of package, 2 = cmdstr,
-// 4 = GoHandle, 5 = CGoHandle, 6 = all imports, 7 = mainstr, 10 = gopy version.
+// 4 = GoHandle, 5 = CGoHandle, 6 = all imports, 7 = mainstr, 8 = C trampolines for
+// callbacks (see cffi_callback.go), 10 = gopy version.
 const goPreambleCFFI = `/*
 cgo stubs for package %[1]s, for use with cffi.
 File is generated by gopy version %[10]s. Do not edit.
@@ -53,6 +54,7 @@ package main
 #if !defined(__STDC_VERSION__) || (__STDC_VERSION__ < 202311L)
 typedef uint8_t bool;
 #endif
+%[8]s
 */
 import "C"
 import (
@@ -148,6 +150,32 @@ func GopyFreeString(s *C.char) {
 	C.free(unsafe.Pointer(s))
 }
 
+// gopyCallbackScope guards a python callback passed to Go, which only exists
+// while the python call it was passed to is running (see cffi_callback.go):
+// close waits for callbacks that are running, and then refuses new ones.
+type gopyCallbackScope struct {
+	mu   sync.RWMutex
+	done bool
+}
+
+func (s *gopyCallbackScope) enter() bool {
+	s.mu.RLock()
+	if s.done {
+		s.mu.RUnlock()
+		println("gopy: callback called after the python call it was passed to returned")
+		return false
+	}
+	return true
+}
+
+func (s *gopyCallbackScope) leave() { s.mu.RUnlock() }
+
+func (s *gopyCallbackScope) close() {
+	s.mu.Lock()
+	s.done = true
+	s.mu.Unlock()
+}
+
 // boolGoToPy converts a Go bool to python-compatible C.char
 func boolGoToPy(b bool) C.char {
 	if b {

bind/cffi_build.py

@@ -130,8 +130,12 @@ def wrapper(name, ret, params, exported):
             "    raise NotImplementedError('%s is not available with the cffi backend')\n" % (name, name)
         )
     args = []
+    setup = []
     for i, (ctype, pname) in enumerate(params):
-        if ctype == "char*":
+        if ctype.startswith("callback:"):
+            setup.append(callback_setup(pname, ctype, i + 1))
+            args.append("_ffi.cast('void*', _cb_%s)" % pname)
+        elif ctype == "char*":
             args.append("_enc(%s, %d)" % (pname, i + 1))
         elif ctype == "bool":
             args.append("(1 if %s else 0)" % pname)
@@ -141,7 +145,7 @@ def wrapper(name, ret, params, exported):
             args.append("_index(%s)" % pname)
         else:
             args.append(pname)
-    body = ["def %s(%s):" % (name, sig), "    _r = _lib.%s(%s)" % (name, ", ".join(args))]
+    body = ["def %s(%s):" % (name, sig)] + setup + ["    _r = _lib.%s(%s)" % (name, ", ".join(args))]
     if ret == "char*":
         body.append("    _r = _dec(_r)")
     elif ret == "bool":
@@ -154,6 +158,34 @@ def wrapper(name, ret, params, exported):
     return "\n".join(body) + "\n"
 
 
+def callback_setup(pname, ctype, argn):
+    """Returns the python source that wraps the callable pname in an
+    ffi.callback, for the C signature in ctype ("callback:void(int64_t,char*)",
+    see cffi_callback.go).  The wrapper passes it on to Go as _cb_<pname>,
+    which is kept referenced by this local variable until the Go call
+    returns: cffi frees a callback as soon as nothing refers to it.
+    """
+    cargs = ctype[len("callback:void("):-1]
+    ctypes = cargs.split(",") if cargs else []
+    names = ["a%d" % i for i in range(len(ctypes))]
+    conv = []
+    for n, t in zip(names, ctypes):
+        if t == "char*":
+            conv.append('_ffi.string(%s).decode("utf-8")' % n)
+        elif t == "bool":
+            conv.append("bool(%s)" % n)
+        else:
+            conv.append(n)
+    cdecl = "void(%s)" % ", ".join("unsigned char" if t == "bool" else t for t in ctypes)
+    return "\n".join([
+        "    if not callable(%s):" % pname,
+        "        raise TypeError('argument %d must be callable, not %%s' %% type(%s).__name__)" % (argn, pname),
+        "    def _cbfn_%s(%s):" % (pname, ", ".join(names)),
+        "        %s(%s)" % (pname, ", ".join(conv)),
+        "    _cb_%s = _ffi.callback(%r, _cbfn_%s)" % (pname, cdecl, pname),
+    ])
+
+
 def complex_wrapper(name, nargs, exported):
     """A plain function whose every argument and return value is
     complex64/128 (see genFuncComplexCFFI, gen_func.go): each argument