df6dd76311
Increment 4: the exported C surface for host callbacks, plus an end-to-end
test that the host can answer from a different thread than the FFI loop.
- declareLibrary now emits two exportc/cdecl procs on every library's
FFIContext (like the event ABI):
<lib>_register_host_fn(ctx, name, fn, userData)
<lib>_host_complete(ctx, token, ret, msg, len)
(the `name` param is spelled `hostFnName` to dodge the macros.name capture
under quote, same class as the existing id/ret collisions.)
- c.nim emits the FFIHostFn typedef + both declarations into <lib>.h
(guarded, format-agnostic), and the timer header is regenerated.
- Verified: the built timer lib exports both symbols.
The e2e (test_ffi_host_e2e) drives the real bridge: a {.ffi.} handler awaits a
{.ffiHost.} call; the host fn (invoked on the FFI thread, non-blocking) hands
the work to a worker thread, which answers via the completion path. The result
resolves on the loop thread and round-trips correctly (orc+refc). It calls the
underlying registerHostFn/completeHostCall directly, since the exported shims
need an --app:lib build; those shims are verified by the symbol check.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
timer example
This example is a self-contained Nimble project demonstrating how to import nim-ffi and use the .ffiCtor. / .ffi. abstraction.
Two ABIs, one library
Every generated library exports two ABIs side by side, and you choose per call site:
| ABI | Header / symbols | Use it for |
|---|---|---|
| Native (pure C) | <lib>.h / <name> |
Same-process / local calls. Flat C structs by value, zero serialization. |
| CBOR | <lib>_cbor.h / <name>_cbor |
Inter-process communication only — a different process or machine, where the request must be serialized to cross the boundary. |
In a shared address space the CBOR round-trip is pure overhead, so default to the native ABI locally and reach for CBOR only when you actually cross a process/machine boundary (see ipc/). The per-language examples below: native C (c_bindings/), native Go (go_bindings/), native/CBOR C++ (cpp_bindings/), CBOR Rust (rust_client/), and CBOR-over-socket IPC (ipc/).
Usage
-
Change into the example directory:
cd examples/timer -
Install the local
ffidependency:nimble install -y ../.. -
Build the example library:
nimble build -
Generate bindings:
nimble genbindings_rust nimble genbindings_cpp
Rust example clients
The Rust client lives in examples/timer/rust_client.
-
Run the sync example:
cd examples/timer/rust_client cargo run --bin rust_client -
Run the Tokio example:
cd examples/timer/rust_client cargo run --bin tokio_client
C++ example
The generated C++ example lives in examples/timer/cpp_bindings.
Build and run it with:
cd examples/timer/cpp_bindings
cmake -S . -B build
cmake --build build
./build/example