diff options
author | Joyee Cheung <joyeec9h3@gmail.com> | 2021-02-21 17:46:58 +0300 |
---|---|---|
committer | Michaël Zasso <targos@protonmail.com> | 2021-03-02 16:08:52 +0300 |
commit | cbfc6b1692c4670625adb7295996f1ba3866de21 (patch) | |
tree | 97b14f7e0d2d350c0cd32df4da4b83135ab3b822 /src | |
parent | dd7a04dc9f3d0dc1cbad218d9ef23b8cd1669fe4 (diff) |
doc: document how to register external bindings for snapshot
PR-URL: https://github.com/nodejs/node/pull/37463
Refs: https://github.com/nodejs/node/issues/35711
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'src')
-rw-r--r-- | src/README.md | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/src/README.md b/src/README.md index a3b54416a0d..d811a628027 100644 --- a/src/README.md +++ b/src/README.md @@ -413,6 +413,55 @@ void Initialize(Local<Object> target, NODE_MODULE_CONTEXT_AWARE_INTERNAL(cares_wrap, Initialize) ``` +If the C++ binding is loaded during bootstrap, it needs to be registered +with the utilities in `node_external_reference.h`, like this: + +```cpp +namespace node { +namespace utils { +void RegisterExternalReferences(ExternalReferenceRegistry* registry) { + registry->Register(GetHiddenValue); + registry->Register(SetHiddenValue); + // ... register all C++ functions used to create FunctionTemplates. +} +} // namespace util +} // namespace node + +// The first argument passed to `NODE_MODULE_EXTERNAL_REFERENCE`, +// which is `util` here, needs to be added to the +// `EXTERNAL_REFERENCE_BINDING_LIST_BASE` list in node_external_reference.h +NODE_MODULE_EXTERNAL_REFERENCE(util, node::util::RegisterExternalReferences) +``` + +Otherwise, you might see an error message like this when building the +executables: + +```console +FAILED: gen/node_snapshot.cc +cd ../../; out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +Unknown external reference 0x107769200. +<unresolved> +/bin/sh: line 1: 6963 Illegal instruction: 4 out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +``` + +You can try using a debugger to symbolicate the external reference. For example, +with lldb's `image lookup --address` command (with gdb it's `info symbol`): + +```console +$ lldb -- out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc +(lldb) run +Process 7012 launched: '/Users/joyee/projects/node/out/Release/node_mksnapshot' (x86_64) +Unknown external reference 0x1004c8200. +<unresolved> +Process 7012 stopped +(lldb) image lookup --address 0x1004c8200 + Address: node_mksnapshot[0x00000001004c8200] (node_mksnapshot.__TEXT.__text + 5009920) + Summary: node_mksnapshot`node::util::GetHiddenValue(v8::FunctionCallbackInfo<v8::Value> const&) at node_util.cc:159 +``` + +Which explains that the unregistered external reference is +`node::util::GetHiddenValue` defined in `node_util.cc`. + <a id="per-binding-state"></a> #### Per-binding state @@ -463,6 +512,12 @@ void InitializeHttpParser(Local<Object> target, } ``` +If the binding is loaded during bootstrap, add it to the +`SERIALIZABLE_OBJECT_TYPES` list in `src/node_snapshotable.h` and +inherit from the `SnapshotableObject` class instead. See the comments +of `SnapshotableObject` on how to implement its serialization and +deserialization. + <a id="exception-handling"></a> ### Exception handling |