Repository navigation
feat: FFI instances, and napi instances on service threads beside wasm modules - #25698
Draft
charlielye wants to merge 8 commits into
Draft
charlielye wants to merge 8 commits into
charlielye wants to merge 8 commits into
Conversation
charlielye
force-pushed
the
cl/ffi-instances
branch
from
October 31, 2026 20:36
1e510d0 to
51dc337
Compare
charlielye
force-pushed
the
cl/ffi-instances
branch
from
November 14, 2026 13:50
51dc337 to
3b7ef9d
Compare
charlielye
force-pushed
the
cl/ffi-instances
branch
from
November 14, 2026 14:44
3b7ef9d to
d99cc48
Compare
charlielye
force-pushed
the
cl/ffi-instances
branch
from
November 14, 2026 14:55
d99cc48 to
7d1e342
Compare
…fiLibrary with host calls answered in JS The C++ FFI server exports <svc>_ipc_ffi_create/_call/_destroy beside _entry, and natively <svc>_ipc_ffi_set_host_call, which hands the library the function its ipc_runtime_host_call forwards to. ipc-runtime's FfiLibrary sets that function when it loads a library, and gains createInstance/callInstance(instance, input, hostCall?)/destroyInstance, so a service's host calls are answered by the JS function passed with each call, on the calling thread. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
A WasmWorker slot now holds a wasm module's main instance or an instance of a service's shared library, with the same host-call routing: a target on the same worker is a synchronous call whichever kind either side is, and anything else is answered on the owning thread. NapiFfiBackend.instance puts a library instance on a worker, of its own or a shared one; NapiFfiBackendSync.instance keeps one on the calling thread. Each backend gets state of its own. Generated packages use instances when their library has them, with worker and hostCall options like wasm's, and fall back to the process's one instance for older libraries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…ts napi instances too Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…s napi transport libbb_avm_sim.so, built like libwsdb_ref.so, joins the binary and the wasm module: @aztec-foundation/bb-avm-sim generates uds,napi,wasm and ships the library in its arch packages, and the native and cross presets build it. ipc-runtime's addon loads it and sets its host-call function, so its wsdb and cdb host calls are answered in JS. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
All four placements of wsdb-ref and the AVM on one thread (napi or wasm each) give the same result, four sessions on their own threads at once match it, and on the calling thread one instance's state is not another's and a host call back into the instance it came from is refused. Each wsdb-ref service is sent Init first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
…stances of their shared libraries Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb
charlielye
force-pushed
the
cl/ffi-instances
branch
from
November 14, 2026 20:27
7d1e342 to
91b15d1
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #25695 (host calls, the TXE on wsdb-ref and the AVM's wasm module), the top of stack #25863. This PR is the eight commits on top.
Why
A process or a wasm module is an instance of its service: the TXE runs one AVM and one world state per session, side by side. A service loaded in-process through napi was not. A library is loaded once per process, and the FFI entry kept one context per library, so every napi backend in a process shared one service, and its calls ran on the libuv pool where nothing chose the thread. This PR makes instances part of the FFI contract and runs napi instances where wasm modules run, so IPC, wasm and napi are three transports for the same model: a backend is an instance of the service, and you choose the thread it runs on.
Since the stack moved napi onto plain shared libraries loaded by ipc-runtime's one Node-API addon (#25861), this PR no longer generates an addon per service. The instances and the host calls live in ipc-runtime's
FfiLibrary, and a service ships only a.so.What changes
The FFI contract: instances, and a host-call setter
<svc>_ipc_ffi_entry, every generated FFI server exports<svc>_ipc_ffi_create,_call(instance, …)and_destroy. An instance is what a connection is over a transport: a context of its own. Calls on one instance must not overlap; calls on different instances may run concurrently, on any threads.SCHEMA_SPEC.mdsays so._entryis_callon one instance of the process, made on first use. Callers that only know_entry(bb.js's wasm, the generated client backends) see no change, and schemas and the wire format don't change.ipc_ffi_create_instance()in place ofipc_ffi_dispatcher(), usuallyreturn std::make_unique<FfiContext<Ctx>>();. bb, bb-avm-sim, wsdb-ref and the echo example do. A service that doesn't fails to link.export_<svc>_ffi!) and Zig (exportFfi()): each instance is aDefault(.{}) handler of the given type.<svc>_ipc_ffi_set_host_call(fn).fnhas the wasm import's signature (ipc_runtime_host_call(target, request, &response), the answer in a buffer from_alloc). The nativeipc_runtime_host_callinipc_codegen/host_call_backend.hppforwards to it, and still answers with an error until one is set.ipc-runtime's
FfiLibrary: instances, with host calls answered in JSFfiLibrarygainshasInstances(),createInstance(),callInstance(instance, bytes, hostCall?)anddestroyInstance(instance).loadNapiFfiLibraryexposes them onNapiFfiLibrary.hostCallof thecallInstancein progress on its thread (a thread-local scope), on the same thread, allocating the answer with that library's_alloc. So a napi instance reaches its host's services the way a wasm module does.call/callAsyncstay, over the process instance, for libraries without instances.ipc-runtime:
ServiceThreadhosts wasm modules and napi instancesWasmWorkerfrom feat: host_call for wasm modules; Simulate in bb-avm-sim's wasm module; the TXE in memory on wsdb-ref #25695 is nowServiceThread(createServiceThread()). A slot on it holds a wasm module or a library instance ({ napi: { libraryPath, ffiName } }). A target on the same thread is called directly; anything else is answered on the owner's thread.Atomics.wait) until the answer arrives; napi is node-only, and node always has shared buffers. For the same reason a napi instance's siblings must answer it synchronously: a wasm module that itself waits on its host fails such a call with a message saying so.NapiFfiBackend.instance({ libraryPath, ffiName, worker, hostCall })puts an instance on a thread (its own by default).NapiFfiBackendSync.instance({ libraryPath, ffiName, hostCall })runs one on the calling thread.workerandhostCalloptions fornapias forwasm. They use instances when the library has them and fall back to the process instance otherwise.Mixing works too: a napi AVM beside a wasm wsdb-ref, or the reverse. Parallelism comes from more threads, as it comes from more processes over IPC.
bb-avm-sim: a shared library
libbb_avm_sim.sois built likelibwsdb_ref.so: the FFI objects as a plain shared library exporting onlyavm_ipc_ffi_*, built by the native and the four cross presets, and shipped in the arch packages beside the binary through--package-native. The package's transports are nowuds,napi,wasm.TXE (labs patch 0005)
TXE_WORLD_STATE=napiruns each session's wsdb-ref and AVM as library instances on the session's thread, in place of wasm modules. Wasm stays the default.Testing
On this head, node 26:
libbb_avm_sim.soand ipc-runtime's addon. The three napi ones:wsdb_ref_test.sh5/5 onprocess-uds,process-shm,napiandwasm.labs-patches/bootstrap.sh check: the series applies, andmake labs-yarn-projectbuilds with patch 0005 (the TXE type-checks against these packages). The TXE suite was not run on this head.Before this PR moved onto
FfiLibrary, with a generated addon per service, the same model passed the TXE suite withTXE_WORLD_STATE=napi(48/48 chunks, at about wasm's speed: the TXE's time is not in AVM or world-state compute), and 8 threads × 25 simulations matched the reference, three times. Neither has been rerun on this head.Not run: TSan on vm2. A read of vm2's statics found only ones set once and then read, which with the stress runs above is evidence, not proof, that instances in one process are safe.
libbb_avm_sim.sowas not built for macOS locally.Not done
_entry, so every client backend in a process shares one instance. Moving them onto instances is a behavior change for their users, such as barretenberg-rs, so it belongs in its own PR.🤖 Generated with Claude Code
https://claude.ai/code/session_015HXzMEGRnmFYs5yXRcAWCb