PCCountProfiling.h (6202B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * vim: set ts=8 sts=2 et sw=2 tw=80: 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 /* 8 * Bytecode-level profiling support based on program counter offset within 9 * functions and overall scripts. 10 * 11 * SpiderMonkey compiles functions and scripts into bytecode representation. 12 * During execution, SpiderMonkey can keep a counter of how often each bytecode 13 * (specifically, bytecodes that are the targets of jumps) is reached, to track 14 * basic information about how many times any particular bytecode in a script 15 * or function is executed. These functions allow this counting to be started 16 * and stopped, and the results of such counting to be examined. 17 * 18 * Accumulated counting data is tracked per "script" (where "script" is either 19 * a JavaScript function from source text or a top-level script or module). 20 * Accumulated PCCount data thus prevents the particular scripts that were 21 * executed from being GC'd. Once PCCount profiling has been stopped, you 22 * should examine and then purge the accumulated data as soon as possible. 23 * 24 * Much of the data tracked here is pretty internal and may only have meaning if 25 * you're familiar with bytecode and Ion details. Hence why these APIs are 26 * "experimental". 27 */ 28 29 #ifndef js_experimental_PCCountProfiling_h 30 #define js_experimental_PCCountProfiling_h 31 32 #include <stddef.h> // size_t 33 34 #include "jstypes.h" // JS_PUBLIC_API 35 36 struct JS_PUBLIC_API JSContext; 37 class JS_PUBLIC_API JSString; 38 39 namespace JS { 40 41 /** 42 * Start PCCount-based profiling if it hasn't already been started. 43 * 44 * This discards previously-accumulated PCCount profiling data from a prior 45 * PCCount profiling session. It also discards all active JIT code (as such 46 * code was compiled to *not* perform PCCount-based profiling), so a brief 47 * performance hit to code execution can be expected after calling this. 48 */ 49 extern JS_PUBLIC_API void StartPCCountProfiling(JSContext* cx); 50 51 /** 52 * Stop PCCount-based profiling if it has been started. 53 * 54 * Internally, this accumulates PCCount profiling results into an array of 55 * (script, script count info) for future consumption. If accumulation fails, 56 * this array will just be empty. 57 * 58 * This also discard all active JIT code (as such code was compiled to perform 59 * PCCount-based profiling), so a brief performance hit to code execution can be 60 * expected after calling this. 61 */ 62 extern JS_PUBLIC_API void StopPCCountProfiling(JSContext* cx); 63 64 /** 65 * Get a count of all scripts for which PCCount profiling data was accumulated, 66 * after PCCount profiling has been stopped. 67 * 68 * As noted above, if an internal error occurred when profiling was stopped, 69 * this function will return 0. 70 */ 71 extern JS_PUBLIC_API size_t GetPCCountScriptCount(JSContext* cx); 72 73 /** 74 * Get a JSON string summarizing PCCount data for the given script, by index 75 * within the internal array computed when PCCount profiling was stopped, of 76 * length indicated by |JS::GetPCCountScriptCount|. 77 * 78 * The JSON string will encode an object of this form: 79 * 80 * { 81 * "file": filename for the script, 82 * "line": line number within the script, 83 * 84 * // OPTIONAL: only if this script is a function 85 * "name": function name 86 * 87 * "totals": 88 * { 89 * "interp": sum of execution counts at all bytecode locations, 90 * "ion": sum of Ion activity counts, 91 * } 92 * } 93 * 94 * There is no inherent ordering to the (script, script count info) pairs within 95 * the array. Callers generally should expect to call this function in a loop 96 * to get summaries for all executed scripts. 97 */ 98 extern JS_PUBLIC_API JSString* GetPCCountScriptSummary(JSContext* cx, 99 size_t script); 100 101 /** 102 * Get a JSON string encoding detailed PCCount data for the given script, by 103 * index within the internal array computed when PCCount profiling was stopped, 104 * of length indicated by |JS::GetPCCountScriptCount|. 105 * 106 * The JSON string will encode an object of this form: 107 * 108 * { 109 * "text": a string containg (possibly decompiled) source of the script, 110 * "line": line number within the script, 111 * 112 * "opcodes": 113 * [ 114 * // array elements of this form, corresponding to the script's 115 * // bytecodes 116 * { 117 * "id": offset of bytecode within script 118 * "line": line number for bytecode, 119 * "name": the name of the bytecode in question, 120 * "text": text of the expression being evaluated, 121 * "counts": 122 * { 123 * // OPTIONAL: only if the count is nonzero 124 * "interp": count of times executed, 125 * }, 126 * ], 127 * 128 * // OPTIONAL: only if the script is executed under Ion 129 * "ion": 130 * [ 131 * // array of elements of this form, corresponding to Ion basic blocks 132 * { 133 * "id": Ion block id, 134 * "offset": Ion block offset, 135 * "successors": 136 * [ 137 * // list of Ion block ids from which execution may proceed after 138 * // this one 139 * ], 140 * "hits": count of times this block was hit during execution, 141 * "code": a string containing the code in this Ion basic block, 142 * } 143 * ], 144 * } 145 * 146 * There is no inherent ordering to the (script, script count info) pairs within 147 * the array. Callers generally should expect to call this function in a loop 148 * to get summaries for all executed scripts. 149 */ 150 extern JS_PUBLIC_API JSString* GetPCCountScriptContents(JSContext* cx, 151 size_t script); 152 153 /** 154 * Purge all accumulated PCCount profiling data, particularly the internal array 155 * that |JS::GetPCCountScript{Count,Summary,Contents}| exposes -- and all that 156 * array's references to previously-executed scripts. 157 */ 158 extern JS_PUBLIC_API void PurgePCCounts(JSContext* cx); 159 160 } // namespace JS 161 162 #endif // js_experimental_PCCountProfiling_h