lib: reintroduce v8 module

[bnoordhuis]

I introduced this module over a year ago in a pull request as the v8
module but it was quickly subsumed by the tracing module.

The tracing module was recently removed again and that is why this
commit introduces the v8 module again, including the new features it
picked up commits d23ac0e and f8076c4.

R=@trevnorris

[bnoordhuis]

Decision time: remove the documentation for the 'gc' event or document that it's dangerous? I'm leaning toward the former. That would let us remove the gc machinery from src/. I don't need it for strong-agent.

[trevnorris]

Agreed. Removing 'gc' event from documentation sounds like a better plan.

[sonewman]

This is actually a really cool idea! It also introduces scope for other v8 based functionality in the future.

[thlorenz]

Probably could reference one of the docs here for this.
I tried to research and test what flags have effect and which don't.
More work needs to be done here, but it's a good place to start looking.

[bnoordhuis]

Can others weigh in? I appreciate Thorsten's effort but I don't want to give off an implied promise of support by linking to documentation. Or is that overly cautious? I lean towards pointing people to --v8-options.

[chrisdickinson]

I'd be in favor of something like:

The V8 options available for a version of node may be determined by running `node --v8-options`. An unofficial, community-maintained list of options and their effects is available [here](https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md).

Since it stresses that the linked guide isn't the "source of truth" -- that lies within v8 -- but gives casual readers a chance to see what's available through this API.

(Also, great work @thlorenz!)

[thlorenz]

@bnoordhuis Totally agree that implied promises given by linking are bad especially if linked content ends up not being maintained.

On the upside, the v8-flags documentation is entirely generated and can be updated whenever the API changes by simply running npm run flag-doc.
The only part of the docs that is manual and gets merged with the auto generated one is specified here. I was secretly hoping for some v8 folks to jump in and help with adding more details via simple update steps

If linking to a third party thing is worrisome I'm open to adapt the generated docs to be included somewhere within the official node docs.

---

Thanks @chrisdickinson macros are lots of fun :)

[bnoordhuis]

@thlorenz I incorporated @chrisdickinson's feedback earlier today; it makes it clear that the linked page is a community effort so I think we're good. Is https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md the best page to link to or is there a better one?

[thlorenz]

Until we generate docs for 12, this is the best one.

[thlorenz]

In general I believe it's a good idea to keep things like v8-flags in user land.
One compelling reason is already to be able to deal with issues due to misunderstandings and/or misuse of these rather advanced and also somewhat unstable features in a separate repo.

I'd imagine you'd get quite a lot of issues just related to the above in this repo if you include it with node proper.

Obviously a point for including them here is the fact that they depend on v8 APIs and thus it is easier to keep them from breaking all the time. I solved this in v8-flags by basically generating the code for the specific node version used via macros, but it's kinda hacky at best.

[bnoordhuis]

@trevnorris Undocumented the 'gc' event, PTAL. I'll follow up with a PR that removes its machinery when this PR lands.

[bnoordhuis]

One compelling reason is already to be able to deal with issues due to misunderstandings and/or misuse of these rather advanced and also somewhat unstable features in a separate repo.

I don't know, I think the documentation makes it clear that unexpected things can happen. I hope and assume people are smart enough not to file bug reports about that.

[bnoordhuis]

@trevnorris Ping. This is blocking another PR.

[bnoordhuis]

@chrisdickinson Can I persuade you to review this PR?

[chrisdickinson]

@bnoordhuis will do. reviewing now.

[chrisdickinson]

You may also want to add V8 to api/doc/_toc.markdown (for it to show up on the index.)

[chrisdickinson]

Pending the _toc.markdown and doc change, LGTM.

[bnoordhuis]

@chrisdickinson Cheers. Incorporated the feedback but I changed node to iojs. PTAL.

[chrisdickinson]

LGTM!

[bnoordhuis]

Thanks everyone, landed in db595b2.