Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: document how to register external bindings for snapshot #37463

Closed
wants to merge 3 commits into from
Closed

doc: document how to register external bindings for snapshot #37463

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f7d3d30
doc: document how to register external bindings for snapshot
joyeecheung Feb 21, 2021
4c4d869
fixup! doc: document how to register external bindings for snapshot
joyeecheung Feb 24, 2021
b996af7
fixup! doc: document how to register external bindings for snapshot
joyeecheung Feb 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
55 changes: 55 additions & 0 deletions src/README.md
View file
Open in desktop
Expand Up @@ -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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might want to also point out that util needs to be listed in the node_external_reference.h EXTERNAL_REFERENCE_BINDING_LIST_BASE macro

```

Otherwise you might see an error message like this when building the
joyeecheung marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -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

Expand Down