Na}{

File Content: `node-postmortem-support.md`

# Postmortem support

Postmortem metadata are constants present in the final build which can be used
by debuggers and other tools to navigate through internal structures of software
when analyzing its memory (either on a running process or a core dump). Node.js
provides this metadata in its builds for V8 and Node.js internal structures.

## V8 postmortem metadata

V8 prefixes all postmortem constants with `v8dbg_`, and they allow inspection of
objects on the heap as well as object properties and references. V8 generates
those symbols with a script (`deps/v8/tools/gen-postmortem-metadata.py`), and
Node.js always includes these constants in the final build.

## Node.js debug symbols

Node.js prefixes all postmortem constants with `nodedbg_`, and they complement
V8 constants by providing ways to inspect Node.js-specific structures, like
`node::Environment`, `node::BaseObject` and its descendants, classes from
`src/utils.h` and others. Those constants are declared in
`src/node_postmortem_metadata.cc`, and most of them are calculated at compile
time.

### Calculating offset of class members

Node.js constants referring to the offset of class members in memory
are calculated at compile time.
Because of that, those class members must be at a fixed offset
from the start of the class. That's not a problem in most cases, but it also
means that those members should always come after any templated member on the
class definition.

For example, if we want to add a constant with the offset for
`ReqWrap::req_wrap_queue_`, it should be defined after `ReqWrap::req_`, because
`sizeof(req_)` depends on the type of T, which means the class definition should
be like this:

```cpp
template <typename T>
class ReqWrap : public AsyncWrap {
 private:
  // req_wrap_queue_ comes before any templated member, which places it in a
  // fixed offset from the start of the class
  ListNode<ReqWrap> req_wrap_queue_;

  T req_;
};
```

instead of:

```cpp
template <typename T>
class ReqWrap : public AsyncWrap {
 private:
  T req_;

  // req_wrap_queue_ comes after a templated member, which means it won't be in
  // a fixed offset from the start of the class
  ListNode<ReqWrap> req_wrap_queue_;
};
```

There are also tests on `test/cctest/test_node_postmortem_metadata.cc` to make
sure all Node.js postmortem metadata are calculated correctly.

## Tools and references

* [llnode](https://github.com/nodejs/llnode): LLDB plugin
* [`mdb_v8`](https://github.com/joyent/mdb_v8): mdb plugin
* [nodejs/post-mortem](https://github.com/nodejs/post-mortem): Node.js
  post-mortem working group

Name	Size	Permission
doc_img	---	0755
adding-new-napi-api.md	2614 bytes	0644
backporting-to-release-lines.md	5856 bytes	0644
building-node-with-ninja.md	1757 bytes	0644
code-of-conduct.md	2175 bytes	0644
collaborator-guide.md	43642 bytes	0644
commit-queue.md	5899 bytes	0644
components-in-core.md	2566 bytes	0644
cpp-style-guide.md	13117 bytes	0644
diagnostic-tooling-support-tiers.md	8181 bytes	0644
feature-request-management.md	3492 bytes	0644
internal-api.md	539 bytes	0644
investigating-native-memory-leaks.md	27720 bytes	0644
issues.md	3392 bytes	0644
maintaining-V8.md	20277 bytes	0644
maintaining-c-ares.md	1673 bytes	0644
maintaining-cjs-module-lexer.md	2259 bytes	0644
maintaining-dependencies.md	4543 bytes	0644
maintaining-http.md	4897 bytes	0644
maintaining-icu.md	8357 bytes	0644
maintaining-npm.md	1224 bytes	0644
maintaining-openssl.md	5380 bytes	0644
maintaining-root-certs.md	3582 bytes	0644
maintaining-shared-library-support.md	4611 bytes	0644
maintaining-the-build-files.md	2458 bytes	0644
maintaining-types-for-nodejs.md	6190 bytes	0644
maintaining-web-assembly.md	4016 bytes	0644
maintaining-zlib.md	900 bytes	0644
node-postmortem-support.md	2588 bytes	0644
offboarding.md	943 bytes	0644
primordials.md	21339 bytes	0644
pull-requests.md	25372 bytes	0644
releases.md	41802 bytes	0644
security-model-strategy.md	2877 bytes	0644
security-release-process.md	8482 bytes	0644
security-steward-on-off-boarding.md	1040 bytes	0644
static-analysis.md	798 bytes	0644
strategic-initiatives.md	3189 bytes	0644
technical-priorities.md	6162 bytes	0644
technical-values.md	2852 bytes	0644
using-internal-errors.md	5018 bytes	0644
using-symbols.md	2376 bytes	0644
writing-and-running-benchmarks.md	23800 bytes	0644
writing-tests.md	16426 bytes	0644

File Content: node-postmortem-support.md

File Content: `node-postmortem-support.md`