repl.txt (3714B)
1 2 {{alias}}( code, [options,] clbk ) 3 Times a snippet. 4 5 If the `asynchronous` option is set to `true`, the implementation assumes 6 that `before`, `after`, and `code` snippets are all asynchronous. 7 Accordingly, these snippets should invoke a `next( [error] )` callback 8 once complete. The implementation wraps the snippet within a function 9 accepting two arguments: `state` and `next`. 10 11 The `state` parameter is simply an empty object which allows the `before`, 12 `after`, and `code` snippets to share state. 13 14 Notes: 15 16 - Snippets always run in strict mode. 17 - Always verify results. Doing so prevents the compiler from performing dead 18 code elimination and other optimization techniques, which would render 19 timing results meaningless. 20 - Executed code is not sandboxed and has access to the global state. You are 21 strongly advised against timing untrusted code. To time untrusted code, 22 do so in an isolated environment (e.g., a separate process with restricted 23 access to both global state and the host environment). 24 - Wrapping asynchronous code does add overhead, but, in most cases, the 25 overhead should be negligible compared to the execution cost of the timed 26 snippet. 27 - When the `asynchronous` option is `true`, ensure that the main `code` 28 snippet is actually asynchronous. If a snippet releases the zalgo, an 29 error complaining about exceeding the maximum call stack size is highly 30 likely. 31 - While many benchmark frameworks calculate various statistics over raw 32 timing results (e.g., mean and standard deviation), do not do this. 33 Instead, consider the fastest time an approximate lower bound for how fast 34 an environment can execute a snippet. Slower times are more likely 35 attributable to other processes interfering with timing accuracy rather 36 than attributable to variability in JavaScript's speed. In which case, the 37 minimum time is most likely the only result of interest. When considering 38 all raw timing results, apply common sense rather than statistics. 39 40 Parameters 41 ---------- 42 code: string 43 Snippet to time. 44 45 options: Object (optional) 46 Options. 47 48 options.before: string (optional) 49 Setup code. Default: `''`. 50 51 options.after: string (optional) 52 Cleanup code. Default: `''`. 53 54 options.iterations: integer|null (optional) 55 Number of iterations. If `null`, the number of iterations is determined 56 by trying successive powers of `10` until the total time is at least 57 `0.1` seconds. Default: `1e6`. 58 59 options.repeats: integer (optional) 60 Number of repeats. Default: `3`. 61 62 options.asynchronous: boolean (optional) 63 Boolean indicating whether a snippet is asynchronous. Default: `false`. 64 65 clbk: Function 66 Callback to invoke upon completion. 67 68 Examples 69 -------- 70 > var code = 'var x = Math.pow( Math.random(), 3 );'; 71 > code += 'if ( x !== x ) {'; 72 > code += 'throw new Error( \'Something went wrong.\' );'; 73 > code += '}'; 74 > function done( error, results ) { 75 ... if ( error ) { 76 ... throw error; 77 ... } 78 ... console.dir( results ); 79 ... }; 80 > {{alias}}( code, done ) 81 e.g., 82 { 83 "iterations": 1000000, 84 "repeats": 3, 85 "min": [ 0, 135734733 ], // [seconds,nanoseconds] 86 "elapsed": 0.135734733, // seconds 87 "rate": 7367311.062526641, // iterations/second 88 "times": [ // raw timing results 89 [ 0, 145641393 ], 90 [ 0, 135734733 ], 91 [ 0, 140462721 ] 92 ] 93 } 94 95 See Also 96 -------- 97