Repository navigation
Usage of Oilpan / V8 C++ Garbage Collector #40786
Description
I have recently read the article about Olipan: https://v8.dev/blog/oilpan-library.
It might be worthwhile investigating if it's something we could use inside Node.js C++ internals to simplify some of our memory management and wrapping logic.
Activity
mcollina commentedon Nov 11, 2021
cc @nodejs/v8 @addaleax @jasnell
joyeecheung commentedon Nov 11, 2021
I think it's worth giving a try. IIUC, we didn't use
EmbedderHeapTracerbecause that only works withBaseObjects that calledMakeWeak(), Oilpan is more powerful so it should work with otherBaseObjects (and other types of native objects that aren't usingBaseObject) - I am not sure if this would necessarily make our memory management simpler though, since Oilpan itself seems more complex than what we use right now to track our native objects.mlippautz commentedon Nov 12, 2021
If you have some bindings use cases that are problematic to get right, or if you just want a GCed C++ object model, then Oilpan may indeed be a great fit.
I'd say the only caveat right now with Oilpan shipped through V8 is that it doesn't (yet) come with containers.
stdcontainers are supported but require using non-incremental tracing for the embedder (--no-incremental-marking-wrappersas of today but the name may change).@joyeecheung You are right, EmbedderHeapTracer doesn't actually manage C++ memory which is why you generally need
MakeWeak()as well. Oilpan is a full-fledged C++ GC, so yes, it is more complicated. However, none of that should be a concern to the embedder. The important piece there is that both types of references, V8->embedder and embedder->V8, are supported by default with V8 so there's no manual management involved there.SalvatorePreviti commentedon Dec 5, 2021
I tried to used Oilpan (cppgc) in a node addon (node 16 and node 17 and also nightly build), but it seems to not be fully linked/exposed. While I can compile a node addon using it, I get runtime linking errors when I try to use it.
Error: dlopen(/xxxxxxxxxx/singularity.node, 0x0001): symbol not found in flat namespace '__ZN5cppgc8internal21RegisteredGCInfoIndexC1EPFvPvEb'
at Object.Module._extensions..node (node:internal/modules/cjs/loader:1179:18)
Is there a plan to support it?
mcollina commentedon Dec 5, 2021
Not at this point. I'm not sure what it would entail for our ABI stability.
SalvatorePreviti commentedon Dec 6, 2021
Makes sense. It seems Google is stabilising the cppgc API. Please, keep us updated, I am really interested in the possibility to use it on node add-ons :)
Thank you.
mcollina commentedon Dec 6, 2021
@SalvatorePreviti if you would like to open a PR, we can discuss it there.
SalvatorePreviti commentedon Dec 6, 2021
A small update, tried to build locally the latest version of node on master and write a unit test in test/addons - it seems that with that oilpan is properly linked and exposed and can be used.
However, cppgc::DefaultPlatform::InitializeProcess is not called yet by anybody, and this should be called once per process to be able to create an heap, and the platform should be exposed. Thinking to add it to ExecuteBootstrapper
For reference, this work in progress branch https://github.com/SalvatorePreviti/node/tree/expose-oilpan
addaleax commentedon Dec 6, 2021
This should probably go into
InitializeOncePerProcess()if it is comparable toV8::Initialize()in when it should be called 👍SalvatorePreviti commentedon Dec 6, 2021
Interestingly, there is deps/v8/include/v8_cppgc.h currently not exported by node.
This seems to be targeted to be used for a common GC heap between JS and C++.
https://chromium.googlesource.com/v8/v8.git/+/HEAD/include/v8-cppgc.h
AttachCppHeap in v8-isolate.h is marked as experimental
https://chromium.googlesource.com/v8/v8.git/+/HEAD/include/v8-isolate.h#940
From a first look it seems to work as a replacement to cppgc::DefaultPlatform::InitializeProcess
At the moment I am still not able to make it work, I get a Signal: 11
SalvatorePreviti commentedon Dec 6, 2021
It seems that this should wait a bit, it seems cppgc and v8_cppgc.h is currently under active development, last commit for v8_cppgc 5 days ago and for cppgc 5 hours ago.
However, from my current understanding of the APIs, and if they do not change, I believe we should initialize a shared CppHeap from v8_cppgc.h at process startup and set it every time to an Isolate when it is relevant to do so (or always)
SalvatorePreviti commentedon Dec 6, 2021
@mlippautz maybe can give some information or make a bit of light on this and the stability of cppgc and v8_cppgc.h?
mlippautz commentedon Dec 7, 2021
cppgc has shipped in v9.4 for Blink where it's used as the production garbage collector for C++.
We are actively working on cppgc and its APIs but everything that you can find on the public API surface in e.g.
include/cppgc/*or ininclude/v8-cppgc.his considered stable and follows V8's general API stability. In other words, as for all other APIs, they are not set in stone but will follow the regular deprecation cycles and we will try hard to allow a smooth migration when removing things.69 remaining items
vm: migrate ContextifyScript to cppgc
deps: V8: cherry-pick 93275031284c
github-actions commentedon Jun 26, 2026
This issue has been marked as stale due to 210 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.
github-actions commentedon Jul 27, 2026
This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 120 days).
If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.