Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(206)

Side by Side Diff: docs/javascript_stack_trace_api.md

Issue 1347153006: [Docs] Add wiki content to Markdown docs (Closed) Base URL: https://chromium.googlesource.com/v8/v8.git@master
Patch Set: Created 5 years, 3 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
(Empty)
1 All internal errors thrown in V8 capture a stack trace when they are created tha t can be accessed from JavaScript through the error.stack property. V8 also has various hooks for controlling how stack traces are collected and formatted, and for allowing custom errors to also collect stack traces. This document outline s V8's JavaScript stack trace API.
2
3 ### Basic stack traces
4
5 By default, almost all errors thrown by V8 have a `stack` property that holds th e topmost 10 stack frames, formatted as a string. Here's an example of a fully formatted stack trace:
6
7 ```
8 ReferenceError: FAIL is not defined
9 at Constraint.execute (deltablue.js:525:2)
10 at Constraint.recalculate (deltablue.js:424:21)
11 at Planner.addPropagate (deltablue.js:701:6)
12 at Constraint.satisfy (deltablue.js:184:15)
13 at Planner.incrementalAdd (deltablue.js:591:21)
14 at Constraint.addConstraint (deltablue.js:162:10)
15 at Constraint.BinaryConstraint (deltablue.js:346:7)
16 at Constraint.EqualityConstraint (deltablue.js:515:38)
17 at chainTest (deltablue.js:807:6)
18 at deltaBlue (deltablue.js:879:2)
19 ```
20
21 The stack trace is collected when the error is created and is the same regardles s of where or how many times the error is thrown. We collect 10 frames because it is usually enough to be useful but not so many that it has a noticeable perfo rmance impact. You can control how many stack frames are collected by setting t he variable
22
23 ```
24 Error.stackTraceLimit
25 ```
26
27 Setting it to 0 will disable stack trace collection. Any finite integer value w ill be used as the maximum number of frames to collect. Setting it to `Infinity ` means that all frames will be collected. This variable only affects the curre nt context, it has to be set explicitly for each context that needs a different value. (Note that what is known as a "context" in V8 terminology corresponds to a page or iframe in Google Chrome). To set a different default value that affe cts all contexts use the
28
29 ```
30 --stack-trace-limit <value>
31 ```
32
33 command-line flag to V8. To pass this flag to V8 when running Google Chrome use
34
35 ```
36 --js-flags="--stack-trace-limit <value>"
37 ```
38
39 ### Stack trace collection for custom exceptions
40 The stack trace mechanism used for built-in errors is implemented using a genera l stack trace collection API that is also available to user scripts. The functi on
41
42 ```
43 Error.captureStackTrace(error, constructorOpt)
44 ```
45
46 adds a stack property to the given `error` object that will yield the stack trac e at the time captureStackTrace was called. The reason for not just returning t he formatted stack trace directly is that this way we can postpone the formattin g of the stack trace until the stack property is accessed and avoid formatting c ompletely if it never is.
47
48 The optional `constructorOpt` parameter allows you to pass in a function value. When collecting the stack trace all frames above the topmost call to this funct ion, including that call, will be left out of the stack trace. This can be usef ul to hide implementation details that won't be useful to the user. The usual w ay of defining a custom error that captures a stack trace would be:
49
50 ```
51 function MyError() {
52 Error.captureStackTrace(this, MyError);
53 // any other initialization
54 }
55 ```
56
57 Passing in MyError as a second argument means that the constructor call to MyErr or won't show up in the stack trace.
58
59 ### Customizing stack traces
60 Unlike Java where the stack trace of an exception is a structured value that all ows inspection of the stack state, the stack property in V8 just holds a flat st ring containing the formatted stack trace. This is for no other reason than com patibility with other browsers. However, this is not hardcoded but only the def ault behavior and can be overridden by user scripts.
61
62 For efficiency stack traces are not formatted when they are captured but on dema nd, the first time the stack property is accessed. A stack trace is formatted b y calling
63
64 ```
65 Error.prepareStackTrace(error, structuredStackTrace)
66 ```
67
68 and using whatever this call returns as the value of the `stack` property. If y ou assign a different function value to `Error.prepareStackTrace` that function will be used to format stack traces. It will be passed the error object that it is preparing a stack trace for and a structured representation of the stack. U ser stack trace formatters are free to format the stack trace however they want and even return non-string values. It is safe to retain references to the struc tured stack trace object after a call to prepareStackTrace completes so that it is also a valid return value. Note that the custom prepareStackTrace function i s immediately called at the point when the error object is created (e.g. with `n ew Error()`).
69
70 The structured stack trace is an Array of CallSite objects, each of which repres ents a stack frame. A CallSite object defines the following methods
71
72 * **getThis**: returns the value of this
73 * **getTypeName**: returns the type of this as a string. This is the name of the function stored in the constructor field of this, if available, otherwise th e object's `[[Class]]` internal property.
74 * **getFunction**: returns the current function
75 * **getFunctionName**: returns the name of the current function, typically its name property. If a name property is not available an attempt will be made to try to infer a name from the function's context.
76 * **getMethodName**: returns the name of the property of this or one of its pr ototypes that holds the current function
77 * **getFileName**: if this function was defined in a script returns the name o f the script
78 * **getLineNumber**: if this function was defined in a script returns the curr ent line number
79 * **getColumnNumber**: if this function was defined in a script returns the cu rrent column number
80 * **getEvalOrigin**: if this function was created using a call to eval returns a CallSite object representing the location where eval was called
81 * **isToplevel**: is this a toplevel invocation, that is, is this the global o bject?
82 * **isEval**: does this call take place in code defined by a call to eval?
83 * **isNative**: is this call in native V8 code?
84 * **isConstructor**: is this a constructor call?
85
86 The default stack trace is created using the CallSite API so any information tha t is available there is also available through this API.
87
88 To maintain restrictions imposed on strict mode functions, frames that have a st rict mode function and all frames below (its caller etc.) are not allow to acces s their receiver and function objects. For those frames, `getFunction()` and `ge tThis()` will return `undefined`.
89
90 ### Compatibility
91 The API described here is specific to V8 and is not supported by any other JavaS cript implementations. Most implementations do provide an `error.stack` propert y but the format of the stack trace is likely to be different from the format de scribed here. The recommended use of this API is
92
93 * Only rely on the layout of the formatted stack trace if you know your code i s running in v8.
94 * It is safe to set `Error.stackTraceLimit` and `Error.prepareStackTrace` rega rdless of which implementation is running your code but be aware that it will on ly have an effect if your code is running in V8.
95
96 ### Appendix: Stack trace format
97 The default stack trace format used by V8 can for each stack frame give the foll owing information:
98
99 * Whether the call is a construct call.
100 * The type of the this value (Type).
101 * The name of the function called (functionName).
102 * The name of the property of this or one of its prototypes that holds the fun ction (methodName).
103 * The current location within the source (location)
104
105 Any of these may be unavailable and different formats for stack frames are used depending on how much of this information is available. If all the above inform ation is available a formatted stack frame will look like this:
106
107 ```
108 at Type.functionName [as methodName] (location)
109 ```
110
111 or, in the case of a construct call
112
113 ```
114 at new functionName (location)
115 ```
116
117 If only one of functionName and methodName is available, or if they are both ava ilable but the same, the format will be:
118
119 ```
120 at Type.name (location)
121 ```
122
123 If neither is available `<anonymous>` will be used as the name.
124
125 The Type value is the name of the function stored in the constructor field of th is. In v8 all constructor calls set this property to the constructor function s o unless this field has been actively changed after the object was created it it will hold the name of the function it was created by. If it is unavailable the `[[Class]]` property of the object will be used.
126
127 One special case is the global object where the Type is not shown. In that case the stack frame will be formatted as
128
129 ```
130 at functionName [as methodName] (location)
131 ```
132
133 The location itself has several possible formats. Most common is the file name, line and column number within the script that defined the current function
134
135 ```
136 fileName:lineNumber:columnNumber
137 ```
138
139 If the current function was created using eval the format will be
140
141 ```
142 eval at position
143 ```
144
145 where position is the full position where the call to eval occurred. Note that this means that positions can be nested if there are nested calls to eval, for i nstance:
146
147 ```
148 eval at Foo.a (eval at Bar.z (myscript.js:10:3))
149 ```
150
151 If a stack frame is within V8's libraries the location will be
152
153 ```
154 native
155 ```
156
157 and if is unavailable it will be
158
159 ```
160 unknown location
161 ```
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698