Skip to content

ffi: allow native exceptions in target library - #66437

Draft
addaleax wants to merge 1 commit into
nodejs:mainfrom
addaleax:ffi-exceptions
Draft

addaleax wants to merge 1 commit into
nodejs:mainfrom
addaleax:ffi-exceptions

Conversation

@addaleax

@addaleax addaleax commented Oct 1, 2026

Copy link
Copy Markdown
Member

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.


AI disclosure: Claude was used for automated debugging and early review.

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.
@addaleax addaleax added request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. ffi Issues and PRs related to experimental Foreign Function Interface support. labels Oct 1, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/ffi
  • @nodejs/gyp

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. ffi Issues and PRs related to experimental Foreign Function Interface support. lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants