From ab79667509a20d65d53fe73928a4ac88c7484a19 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Thu, 1 Oct 2026 09:38:57 +0200 Subject: [PATCH] ffi: allow native exceptions in target library We currently do not allow callbacks to throw exceptions (including the special termination exception used when e.g. tearing down worker threads), because we have no way of generically propagating exceptions through the native layer back to the calling JS code that originally entered the native code. However, exceptions may be explicitly or implicitly enabled, e.g. when the target library is a C++ library, or when the compiler was configured to emit unwinding information as part of the code generation process. Since this change currently makes no attempt to automatically discover the library's level of exception support (which would likely be possible, but platform-dependent), it expects users to actively indicate whether this feature is available in the called library. Since this change requires access to native exceptions and most of Node.js is built without support for it, a small part of the code is split out into a new GYP target where exceptions are enabled, and as a part of the Node.js source is also on the path for passing exceptions through, the compiler flags for it are changed to include `-funwind-tables`. The total effect on compiled binary sizes of this patch is approximately 15 kB, which is negligible compared to the total size of the binary. --- doc/api/ffi.md | 48 +++++-- lib/ffi.js | 12 +- node.gyp | 40 ++++++ src/ffi/cxx_exceptions.cc | 31 +++++ src/ffi/cxx_exceptions.h | 41 ++++++ src/node_ffi.cc | 125 ++++++++++++++---- src/node_ffi.h | 6 +- ...st-ffi-callback-throw-exception-support.js | 25 ++++ .../test-ffi-callback-worker-termination.js | 30 +++-- 9 files changed, 309 insertions(+), 49 deletions(-) create mode 100644 src/ffi/cxx_exceptions.cc create mode 100644 src/ffi/cxx_exceptions.h create mode 100644 test/ffi/test-ffi-callback-throw-exception-support.js diff --git a/doc/api/ffi.md b/doc/api/ffi.md index 342acfbec503..0c4a900dbd34 100644 --- a/doc/api/ffi.md +++ b/doc/api/ffi.md @@ -206,11 +206,14 @@ const { suffix } = require('node:ffi'); const path = `libsqlite3.${suffix}`; ``` -## `ffi.dlopen(path[, definitions])` +## `ffi.dlopen(path[, definitions[, options]])`