From 70cd01fe2096e16dc6e9ec899b66c9767dddea63 Mon Sep 17 00:00:00 2001 From: Benedikt Meurer Date: Mon, 29 Oct 2018 09:16:00 +0100 Subject: [PATCH 1/2] [docs] Add documentation for zero-cost async stack traces. Bug: v8:7522 Ref: nodejs/node#11865 Design-Document: http://bit.ly/v8-zero-cost-async-stack-traces --- src/docs/stack-trace-api.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/docs/stack-trace-api.md b/src/docs/stack-trace-api.md index 6b6b24788..97fa94a8a 100644 --- a/src/docs/stack-trace-api.md +++ b/src/docs/stack-trace-api.md @@ -39,6 +39,18 @@ To pass this flag to V8 when running Google Chrome, use: --js-flags='--stack-trace-limit ' ``` +## Async stack traces + +The `--async-stack-traces` flag (currently turned off by default) enables the new [zero-cost async stack traces](http://bit.ly/v8-zero-cost-async-stack-traces), which enriches the `stack` property of the `Error` instances with async stack frames, i.e. `await` locations in the code. These async frames are marked with `async` in the `stack` string: + +``` +ReferenceError: FAIL is not defined + at bar () + at async foo () +``` + +At the time of this writing it is limited to `await` locations and `Promise.all()`, since for those cases the engine can reconstruct the necessary information without any additional overhead (that's why it's zero-cost). + ## Stack trace collection for custom exceptions The stack trace mechanism used for built-in errors is implemented using a general stack trace collection API that is also available to user scripts. The function @@ -87,6 +99,9 @@ The structured stack trace is an array of `CallSite` objects, each of which repr - `isEval`: does this call take place in code defined by a call to `eval`? - `isNative`: is this call in native V8 code? - `isConstructor`: is this a constructor call? +- `isAsync`: is this an async call (i.e. `await` or `Promise.all()`)? +- `isPromiseAll`: is this an async call to `Promise.all()`? +- `getPromiseIndex`: returns the index of the promise element that was followed in `Promise.all()` for async stack traces, or `null` if the `CallSite` is not a `Promise.all()` call. The default stack trace is created using the CallSite API so any information that is available there is also available through this API. From 11afa09a4fb2d0bee5fa32ae04ee7df3aa3225fd Mon Sep 17 00:00:00 2001 From: Mathias Bynens Date: Mon, 29 Oct 2018 12:33:19 +0100 Subject: [PATCH 2/2] Minor nits --- src/docs/stack-trace-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/stack-trace-api.md b/src/docs/stack-trace-api.md index 97fa94a8a..278992ab4 100644 --- a/src/docs/stack-trace-api.md +++ b/src/docs/stack-trace-api.md @@ -41,7 +41,7 @@ To pass this flag to V8 when running Google Chrome, use: ## Async stack traces -The `--async-stack-traces` flag (currently turned off by default) enables the new [zero-cost async stack traces](http://bit.ly/v8-zero-cost-async-stack-traces), which enriches the `stack` property of the `Error` instances with async stack frames, i.e. `await` locations in the code. These async frames are marked with `async` in the `stack` string: +The `--async-stack-traces` flag (currently turned off by default) enables the new [zero-cost async stack traces](https://bit.ly/v8-zero-cost-async-stack-traces), which enriches the `stack` property of `Error` instances with async stack frames, i.e. `await` locations in the code. These async frames are marked with `async` in the `stack` string: ``` ReferenceError: FAIL is not defined @@ -49,7 +49,7 @@ ReferenceError: FAIL is not defined at async foo () ``` -At the time of this writing it is limited to `await` locations and `Promise.all()`, since for those cases the engine can reconstruct the necessary information without any additional overhead (that's why it's zero-cost). +At the time of this writing, this functionality is limited to `await` locations and `Promise.all()`, since for those cases the engine can reconstruct the necessary information without any additional overhead (that’s why it’s zero-cost). ## Stack trace collection for custom exceptions