Skip to main content

Sync vs Async

arkffi’s default C function calls are synchronouslib.symbols.add(2.0, 3.0) blocks the current thread until the function returns. For expensive operations (complex computation, I/O), use callAsync to offload the call to a libuv worker thread and get a Promise back.

ffi.callAsync

Syntax

Parameters

AsyncCFunction

AsyncCFunction is the async counterpart of CFunction with the same signature, returning Promise<number>. No defineFunction needed — works directly with function pointers:

Comparison

Usage with dlopen

Implementation

  1. callAsync parses arguments on the JS thread and creates a napi_async_work
  2. The worker thread executes DispatchCallRaw — a pure C function pointer call with no NAPI involvement
  3. On completion, the Promise is resolved on the JS thread
  4. The JS main thread is never blocked

Limitations

  • String return types are not supported (no async version of callString)
  • Callbacks (JSCallback) cannot be invoked from the async worker thread
  • The function must be registered via defineFunction first