Repository navigation
Support Node.js embedder objects and bindings in the snapshot #37476
Description
Here is a list of embedder object classes we have in core. In order to make userland snapshot possible (#35711) we should support as many as possible of them.
Some of them can't simply be deserialized - for example, the HandleWraps, because theoretically we can't resurrect a uv_handle_t from a snapshot, at best we can restore them by creating new ones, but that involves more work (which is system-specific) than "just deserialize the object". Some of them may be helper singletons that we can just throw away at serialization time and recreate upon deserialization, and some of them may not be supposed to be supported.
-
class HistogramBase : public BaseObject: src/histogram.h -
class ModuleWrap : public BaseObject: src/module_wrap.h -
class Blob : public BaseObject: src/node_blob.h -
class BlobBindingData : public BaseObject: src/node_blob.h -
class MicrotaskQueueWrap : public BaseObject: src/node_contextify.h -
class ContextifyScript : public BaseObject: src/node_contextify.h -
class CompiledFnEntry final : public BaseObject: src/node_contextify.h -
class BindingData : public BaseObject: src/node_http_parser.cc -
class ConverterObject : public BaseObject: src/node_i18n.h -
class JSTransferable : public BaseObject: src/node_messaging.h -
class FastHrtime : public BaseObject: src/node_process_methods.cc (WIP at bootstrap: implement run-time user-land snapshots via --build-snapshot and --snapshot-blob #38905) -
class SerializerContext : public BaseObject: src/node_serdes.cc -
class DeserializerContext : public BaseObject: src/node_serdes.cc -
class SnapshotableObject : public BaseObject: src/node_snapshotable.h -
class NodeCategorySet : public BaseObject: src/node_trace_events.cc -
class WeakReference : public BaseObject: src/node_util.cc: src: support WeakReference, diagnostics_channel and net in the snapshot #44193 -
class WASI : public BaseObject: src/node_wasi.h
The following are probably less likely to need support since they involve some kind of asynchronous state or references to opened system handles.
-
class Http2State : public BaseObject: src/node_http2_state.h -
class AsyncWrap : public BaseObject: src/async_wrap.h -
class PromiseWrap : public AsyncWrap: src/async_wrap.cc -
class ChannelWrap : public AsyncWrap: src/cares_wrap.cc -
class QueryWrap : public AsyncWrap: src/cares_wrap.cc -
class HandleWrap : public AsyncWrap: src/handle_wrap.h -
class HeapSnapshotStream : public AsyncWrap: src/heap_utils.cc -
class JSBindingsConnection : public AsyncWrap: src/inspector_js_api.cc -
class JSStream : public AsyncWrap: src/js_stream.h -
class FixedSizeBlobCopyJob : public AsyncWrap: src/node_blob.h -
class DirHandle : public AsyncWrap: src/node_dir.h -
class FileHandle final : public AsyncWrap: src/node_file.h -
class Http2Stream : public AsyncWrap: src/node_http2.h -
class Http2Session : public AsyncWrap: src/node_http2.h -
class Http2Ping : public AsyncWrap: src/node_http2.h -
class Http2Settings : public AsyncWrap: src/node_http2.h -
class Parser : public AsyncWrap: src/node_http_parser.cc -
class WorkerHeapSnapshotTaker : public AsyncWrap: src/node_worker.cc -
class Worker : public AsyncWrap: src/node_worker.h -
class CompressionStream : public AsyncWrap: src/node_zlib.cc -
class ReqWrap : public AsyncWrap: src/req_wrap.h -
class StreamPipe : public AsyncWrap: src/stream_pipe.h -
class BindingData : public SnapshotableObject: src/node_file.h -
class BindingData : public SnapshotableObject: src/node_v8.h -
class IntervalHistogram : public HandleWrap: src/histogram.h -
class MessagePort : public HandleWrap: src/node_messaging.h -
class StatWatcher : public HandleWrap: src/node_stat_watcher.h -
class TraceSigintWatchdog : public HandleWrap: src/node_watchdog.h -
class ProcessWrap : public HandleWrap: src/process_wrap.cc -
class SignalWrap : public HandleWrap: src/signal_wrap.cc -
class LibuvStreamWrap : public HandleWrap: src/stream_wrap.h -
class UDPWrap final : public HandleWrap: src/udp_wrap.h -
class Http2Stream::Provider::Stream : public Http2Stream: src/node_http2.h -
class ZlibStream : public CompressionStream: src/node_zlib.cc -
class BrotliCompressionStream : public CompressionStream: src/node_zlib.cc -
class GetAddrInfoReqWrap : public ReqWrap: src/cares_wrap.cc -
class GetNameInfoReqWrap : public ReqWrap: src/cares_wrap.cc -
class ConnectWrap : public ReqWrap: src/connect_wrap.h -
class FSReqBase : public ReqWrap: src/node_file.h -
class FileHandleReadWrap final : public ReqWrap: src/node_file.h -
class CloseReq final : public ReqWrap: src/node_file.h -
class SendWrap : public ReqWrap: src/udp_wrap.cc -
class ELDHistogram : public IntervalHistogram: src/node_perf.h -
class ConnectionWrap : public LibuvStreamWrap: src/connection_wrap.h -
class TTYWrap : public LibuvStreamWrap: src/tty_wrap.h -
class JSUDPWrap final : public UDPWrap: src/js_udp_wrap.cc -
class Http2StreamListener : public Stream: src/node_http2.h -
class ShutdownWrap : public Stream: src/stream_base.h -
class WriteWrap : public Stream: src/stream_base.h -
class ReportWritesToJSStreamListener : public Stream: src/stream_base.h -
class StreamBase : public Stream: src/stream_base.h -
class ReadableListener : public Stream: src/stream_pipe.h -
class WritableListener : public Stream: src/stream_pipe.h -
class FSReqCallback final : public FSReqBase: src/node_file.h -
class FSReqPromise final : public FSReqBase: src/node_file.h -
class PipeWrap : public ConnectionWrap: src/pipe_wrap.h -
class TCPWrap : public ConnectionWrap: src/tcp_wrap.h -
class SimpleShutdownWrap : public ShutdownWrap: src/stream_base.h -
class SimpleWriteWrap : public WriteWrap: src/stream_base.h -
class EmitToJSStreamListener : public ReportWritesToJSStreamListener: src/stream_base.h -
class CustomBufferJSListener : public ReportWritesToJSStreamListener: src/stream_base.h
Another list for external references registration:
- fs
- os
- uv
- v8
- icu
- url
- blob
- util
- wasi
- zlib
- http2
- types
- buffer
-
config(all properties) - crypto (src: include crypto in the bootstrap snapshot #42203)
- dtrace
- errors
- fs_dir
- report
- serdes
- timers
- worker
- options
-
symbols(all properties) - profiler
- tcp_wrap
- tls_wrap
- tty_wrap
- udp_wrap
- watchdog
- inspector
- js_stream
- messaging
- pipe_wrap
- async_wrap
- block_list
- cares_wrap
- contextify
- heap_utils
- mksnapshot
- spawn_sync
- task_queue
- credentials
- http_parser
- js_udp_wrap
- module_wrap
- performance
- signal_wrap
- stream_pipe
- stream_wrap
- process_wrap
- trace_events
- fs_event_wrap
- native_module
- string_decoder
- process_methods
Activity
joyeecheung commentedon Feb 22, 2021
I'll be looking into the ones in
module_wrap.handnode_contextify.hso that we can include the user modules in the snapshot. Also we need a better story for fast API objects likeFastHrtimethough right now we don't use fast API much in core so it's low priority.joyeecheung commentedon Feb 22, 2021
cc @nodejs/startup
devsnek commentedon Feb 22, 2021
ModuleWrap is blocked on v8:10855
XadillaX commentedon Feb 23, 2021
So we have to do some division of labor?
joyeecheung commentedon Feb 24, 2021
@XadillaX Just a FYI and to avoid stepping on each other's toes :) I suppose the majority of the list should be crossed out as invalid so there isn't actually that much work to do. Maybe it would be good to have a call about the list to figure out what should be excluded, or maybe discussing in the thread is already enough.
joyeecheung commentedon Feb 24, 2021
Maybe a good place to start is to document (that is, adding comments about) exactly what these classes are and what their fields are for.
bootstrap: print information for snapshot at environment exit in debug
targos commentedon Aug 9, 2021
@joyeecheung the OP probably needs an update.
jasnell commentedon Aug 9, 2021
Fwiw, Blob objects likely should not be serialized. They should not live beyond the process in which they were created.
[-]Support (de)serialization of Node.js embedder objects in the snapshot[/-][+]Support Node.js embedder objects and bindings in the snapshot[/+]src: register external references in crypto bindings
src: register external references in os bindings
src: register external references in crypto bindings
32 remaining items
src: iterate over base objects to prepare for snapshot
src: support WeakReference in snapshot
src: iterate over base objects to prepare for snapshot
src: support WeakReference in snapshot
src: iterate over base objects to prepare for snapshot
src: support WeakReference in snapshot
src: iterate over base objects to prepare for snapshot
src: support WeakReference in snapshot
github-actions commentedon Jun 27, 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 28, 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.