WIP V8 API usage in Node.js #26929

sam-github · 2019-03-26T16:07:00Z

I've had these notes around for a while, as a result of me spending some time trying to figure out how the V8 API works. Even in this rough draft form, I hope it might lower the barrier to entry for anybody wanting to work on node's C++.

I'll keep working on this as I have time, though I expect it to be slow. I'd be happy to have comments on inaccuracies or XXX in the text, and the "allow edits from maintainers" is ticked. V8 experts, please don't be shy to push fixups if you are so inclined!

V8's API is not very documented, so many (most?) of us just find existing code that does what we want to do and copy it, but #26868 shows this can be problematic, because the expectations for how C++ should be written are evolving, and choosing the wrong existing code as a template can spread code practices that are now discouraged. Hopefully, this guide can point people to the current expectations.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

nodejs-github-bot · 2019-03-26T16:07:04Z

@sam-github build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/3056/pipeline

devsnek · 2019-03-26T16:16:40Z

Full build of v8 docs from the source comments and such is available here: https://v8.paulfryzel.com/docs/master/ (yes, you have to accept the invalid cert, paul always forgets to update his certs)

i also find https://cs.chromium.org/chromium/src/v8/include/v8.h very helpful, as you can start with a public api and work your way through it thanks to how cs.chromium.org links structures.

doc/guides/V8-api-for-node.md

addaleax · 2019-03-26T16:20:53Z

doc/guides/V8-api-for-node.md

+  JavaScript code to run in a single instance of V8. The motivation for using
+  contexts in V8 was so that each window and iframe in a browser can have its
+  own fresh JavaScript environment.
+  XXX Node uses one context, mostly, does vm. create new ones? anything else?


I think that’s about it.

One kind-of-open question is whether we want Node’s own APIs to eventually supports multiple contexts, but that would be a major change to some of our internals…

does vm (or anything else) create new Contexts?

Yes, the vm module does that. It’s currently the only public API for that.

addaleax · 2019-03-26T16:21:19Z

doc/guides/V8-api-for-node.md

+  own fresh JavaScript environment.
+  XXX Node uses one context, mostly, does vm. create new ones? anything else?
+
+  Can get from `isolate->GetCurrentContext()`


… which is why this should be the same as env->context() in almost all cases.

addaleax · 2019-03-26T16:22:54Z

doc/guides/V8-api-for-node.md

+  Can get from `isolate->GetCurrentContext()`
+
+
+XXX Function vs FunctionTemplate ... wth?


The distinction isn’t that important to us because we don’t expose many APIs for more than one context (MessagePort being the only exception I can think of right now) – essentially, a FunctionTemplate can be used to create functionally identical function instances for multiple contexts.

FunctionTemplates are also useful because they give you an ObjectTemplate (through InstanceTemplate()) that you can use to define internal fields. You can't do that with regular Functions.

addaleax · 2019-03-26T16:24:10Z

doc/guides/V8-api-for-node.md

+- `Local<Object> exports`: where to put exported properties, conventionally
+  called `target` in node
+- `Local<Value> module`: conventionally unused in node
+XXX what is this for? addon docs don't mention or use it


It should be the same value that module has in CJS scripts – I think this is mostly there so that it matches the addon API more closely? We can remove it if we want, I’d say.

addaleax · 2019-03-26T16:25:55Z

doc/guides/V8-api-for-node.md

+XXX what is this for? addon docs don't mention or use it
+- `Local<Context> context`:
+- void* priv: not commonly used
+XXX where is it ever used? for what?


I don’t think anybody uses this in practice, neither Node.js itself nor addons. I think the idea was for it to function as sort of a opaque pointer, but that never became useful due to the way that we load addons?

addaleax · 2019-03-26T16:29:09Z

Also, thanks for starting this!

doc/guides/V8-api-for-node.md

bnoordhuis · 2019-03-26T18:39:53Z

doc/guides/V8-api-for-node.md

+  Can get from `isolate->GetCurrentContext()`
+
+
+XXX Function vs FunctionTemplate ... wth?


FunctionTemplates are also useful because they give you an ObjectTemplate (through InstanceTemplate()) that you can use to define internal fields. You can't do that with regular Functions.

bnoordhuis · 2019-03-26T18:42:12Z

doc/guides/V8-api-for-node.md

+
+  Commonly used convenience methods:
+  - ThrowError/TypeError/RangeError/ErrnoException/...
+  XXX why are some called Error and others called Exception?


Legacy :-) ThrowErrnoException() and ThrowUVException() are old, the others are newer. I'd be okay with renaming them if that clears up the confusion / cognitive dissonance.

doc/guides/V8-api-for-node.md

bnoordhuis · 2019-03-26T18:49:36Z

doc/guides/V8-api-for-node.md

+(manually managed scope). Constructors (String::New) seem to return Locals.
+
+`return Local<Array>();` ... seems to do exactly what you are not supposed
+to do... whats up?


It's okay to return empty handles, just not handles that point to something without going through EscapableHandleScope::Escape().

addaleax · 2019-04-08T18:37:57Z

@sam-github Btw, I’m still grateful for you doing this, but feel free to let us know if you would like someone to take over this PR :)

sam-github · 2019-04-09T14:59:59Z

It's very close to the top of my list! And I'm in the process fixing that abort caused by a throwing setter on Object.prototype which you gave me a demo for, which I hope will help me with this.

sam-github · 2019-04-09T22:45:47Z

I integrated a bunch of the extra information, and that's as far as I got for now.

Btw, I don't mind if anybody pushes additional commits directly to this branch.

sam-github · 2019-04-09T22:46:05Z

@devsnek thanks for the links, are you sure they are up to date? https://v8.paulfryzel.com/docs/master/classv8_1_1_maybe.html doesn't have Check() and our v8.h does.

richardlau · 2019-04-09T22:46:22Z

doc/guides/V8-api-for-node.md

@@ -3,29 +3,50 @@
 v8 docs, not particularly useful:
 - https://v8.dev/docs

+v8 docs, generated from master:
+- https://v8.paulfryzel.com/docs/master/


I think these are out of date? Also Firefox warns that it's using an expired certificate.

It's documenting V8 6.9 so yeah, pretty stale.

Could we fork this https://github.com/paulfryzel/v8-doxygen, and redeploy it to GH pages or Nodejs.org

Repo: https://github.com/gengjiawen/v8-docs
Docs: https://circleci.com/gh/gengjiawen/v8-docs/6#artifacts/containers/0
You can download the docs artifact here.

Online preview by gitlab: https://gengjiawen.gitlab.io/v8-docs/.

bnoordhuis · 2019-05-01T05:14:20Z

doc/guides/V8-api-for-node.md

@@ -3,29 +3,50 @@
 v8 docs, not particularly useful:
 - https://v8.dev/docs

+v8 docs, generated from master:
+- https://v8.paulfryzel.com/docs/master/


It's documenting V8 6.9 so yeah, pretty stale.

bnoordhuis · 2019-05-01T05:17:56Z

doc/guides/V8-api-for-node.md

+    the only references to an object are from weak persistent handles.
+  - A `v8::Global<>` (alias of a `UniquePersistent<>`) handle relies on C++
+    constructors and destructors to manage the lifetime of the underlying
+    object. We don’t use `UniquePersistent` in Node.js.


I'd drop the notes about UniquePersistent, that's its old name and will probably go away entirely someday.

bnoordhuis · 2019-05-01T05:20:47Z

doc/guides/V8-api-for-node.md

+  - Boolean becomes 1/0 as int, "true"/"false" as strings, etc.
+  - Numbers become false as Boolean (for any value), -3 casts to String "-3"
+  - Functions become numerically zero, and "function () { const hello=0; }" as a
+    String


Sam, can you remove these three bullet points?

bnoordhuis · 2019-05-01T05:22:40Z

doc/guides/V8-api-for-node.md

+- To<T> will convert values in fairly typical js way:
+   ... never seems to be used by node?
+   AFAICT, is identical to the As<> route, except for Boolean, which is always
+   false with As<T>(), but is "expected" with ToT().


Can you remove this paragraph? There's no templated To<T>.

(There's Maybe<T>::To() but that's different.)

gengjiawen · 2019-05-03T16:39:38Z

Add a link to CONTRIBUTING.md ?

gengjiawen · 2019-05-05T07:21:54Z

doc/guides/V8-api-for-node.md

+
+- `Local<...>`: A local handle is a pointer to an object. All V8 objects are
+  accessed using handles, they are necessary because of the way the V8 garbage
+  collector works.  Local handles can only be allocated on the stack, in a


Extra space before Local.

gengjiawen · 2019-05-05T13:09:41Z

doc/guides/V8-api-for-node.md

+   AFAICT, is identical to the As<> route, except for Boolean, which is always
+   false with As<T>(), but is "expected" with ToT().
+
+- FunctionCallbackInfo


Document args.Holder() ?

This aims to help explain some of the internal patterns and utilities that we use. It is by no means exhaustive, and suggestions for additions are welcome. Some of this is based on the existing work from nodejs#26929. Refs: nodejs#26929

This aims to help explain some of the internal patterns and utilities that we use. It is by no means exhaustive, and suggestions for additions are welcome. Some of this is based on the existing work from #26929. Refs: #26929 PR-URL: #30552 Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Jiawen Geng <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Michael Dawson <[email protected]>

sam-github · 2019-11-28T21:30:39Z

@addaleax did this better in #30552

This aims to help explain some of the internal patterns and utilities that we use. It is by no means exhaustive, and suggestions for additions are welcome. Some of this is based on the existing work from #26929. Refs: #26929 PR-URL: #30552 Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Jiawen Geng <[email protected]> Reviewed-By: David Carlier <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Michael Dawson <[email protected]>

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Mar 26, 2019

sam-github force-pushed the v8-api-for-node branch from a908593 to c51091d Compare March 26, 2019 16:12

WIP V8 API usage in Node.js

7a63b32

sam-github force-pushed the v8-api-for-node branch from c51091d to 7a63b32 Compare March 26, 2019 16:14

addaleax reviewed Mar 26, 2019

View reviewed changes

sam-github mentioned this pull request Mar 26, 2019

Decorate crypto openssl errors with .code, .reason, ... #26868

Closed

4 tasks

bnoordhuis reviewed Mar 26, 2019

View reviewed changes

shiftkey mentioned this pull request Mar 27, 2019

differentiate draft PRs from normal PRs in the PR list desktop/desktop#7170

Closed

fixup! WIP V8 API usage in Node.js

5faa4c1

richardlau reviewed Apr 9, 2019

View reviewed changes

bnoordhuis reviewed May 1, 2019

View reviewed changes

gengjiawen mentioned this pull request May 3, 2019

doc: add glossary.md #27517

Closed

4 tasks

gengjiawen reviewed May 5, 2019

View reviewed changes

Trott force-pushed the master branch from 1ecc406 to 49cf67e Compare September 17, 2019 16:51

addaleax self-assigned this Nov 19, 2019

addaleax mentioned this pull request Nov 20, 2019

src,doc: add C++ internals documentation #30552

Closed

3 tasks

sam-github closed this Nov 28, 2019

sam-github deleted the v8-api-for-node branch November 28, 2019 22:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP V8 API usage in Node.js #26929

WIP V8 API usage in Node.js #26929

sam-github commented Mar 26, 2019

nodejs-github-bot commented Mar 26, 2019

devsnek commented Mar 26, 2019

addaleax Mar 26, 2019

sam-github Apr 9, 2019

addaleax Apr 9, 2019

addaleax Mar 26, 2019

addaleax Mar 26, 2019

bnoordhuis Mar 26, 2019

addaleax Mar 26, 2019

addaleax Mar 26, 2019

addaleax commented Mar 26, 2019

bnoordhuis Mar 26, 2019

bnoordhuis Mar 26, 2019

bnoordhuis Mar 26, 2019

addaleax commented Apr 8, 2019

sam-github commented Apr 9, 2019

sam-github commented Apr 9, 2019

sam-github commented Apr 9, 2019

richardlau Apr 9, 2019

bnoordhuis May 1, 2019

gengjiawen May 5, 2019

gengjiawen May 7, 2019 •

edited

Loading

gengjiawen May 7, 2019 •

edited

Loading

bnoordhuis May 1, 2019

bnoordhuis May 1, 2019

bnoordhuis May 1, 2019

bnoordhuis May 1, 2019

gengjiawen commented May 3, 2019

gengjiawen May 5, 2019

gengjiawen May 5, 2019

sam-github commented Nov 28, 2019

		Can get from `isolate->GetCurrentContext()`


		XXX Function vs FunctionTemplate ... wth?

WIP V8 API usage in Node.js #26929

WIP V8 API usage in Node.js #26929

Conversation

sam-github commented Mar 26, 2019

Checklist

nodejs-github-bot commented Mar 26, 2019

devsnek commented Mar 26, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addaleax commented Mar 26, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addaleax commented Apr 8, 2019

sam-github commented Apr 9, 2019

sam-github commented Apr 9, 2019

sam-github commented Apr 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gengjiawen May 7, 2019 • edited Loading

Choose a reason for hiding this comment

gengjiawen May 7, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gengjiawen commented May 3, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sam-github commented Nov 28, 2019

gengjiawen May 7, 2019 •

edited

Loading

gengjiawen May 7, 2019 •

edited

Loading