Skip to content

Commit

Permalink
doc: document how to register external bindings for snapshot
Browse files Browse the repository at this point in the history
PR-URL: #37463
Refs: #35711
Reviewed-By: Juan José Arboleda <[email protected]>
Reviewed-By: James M Snell <[email protected]>
  • Loading branch information
joyeecheung authored and targos committed Jun 11, 2021
1 parent 2168e95 commit bc6ea63
Showing 1 changed file with 55 additions and 0 deletions.
55 changes: 55 additions & 0 deletions src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,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

Expand Down Expand Up @@ -467,6 +516,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
Expand Down

0 comments on commit bc6ea63

Please sign in to comment.