diff options
Diffstat (limited to '')
| -rw-r--r-- | js/public/experimental/PCCountProfiling.h | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/js/public/experimental/PCCountProfiling.h b/js/public/experimental/PCCountProfiling.h new file mode 100644 index 0000000000..132d48bcae --- /dev/null +++ b/js/public/experimental/PCCountProfiling.h @@ -0,0 +1,162 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * vim: set ts=8 sts=2 et sw=2 tw=80: + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +/* + * Bytecode-level profiling support based on program counter offset within + * functions and overall scripts. + * + * SpiderMonkey compiles functions and scripts into bytecode representation. + * During execution, SpiderMonkey can keep a counter of how often each bytecode + * (specifically, bytecodes that are the targets of jumps) is reached, to track + * basic information about how many times any particular bytecode in a script + * or function is executed. These functions allow this counting to be started + * and stopped, and the results of such counting to be examined. + * + * Accumulated counting data is tracked per "script" (where "script" is either + * a JavaScript function from source text or a top-level script or module). + * Accumulated PCCount data thus prevents the particular scripts that were + * executed from being GC'd. Once PCCount profiling has been stopped, you + * should examine and then purge the accumulated data as soon as possible. + * + * Much of the data tracked here is pretty internal and may only have meaning if + * you're familiar with bytecode and Ion details. Hence why these APIs are + * "experimental". + */ + +#ifndef js_experimental_PCCountProfiling_h +#define js_experimental_PCCountProfiling_h + +#include <stddef.h> // size_t + +#include "jstypes.h" // JS_PUBLIC_API + +struct JS_PUBLIC_API JSContext; +class JS_PUBLIC_API JSString; + +namespace JS { + +/** + * Start PCCount-based profiling if it hasn't already been started. + * + * This discards previously-accumulated PCCount profiling data from a prior + * PCCount profiling session. It also discards all active JIT code (as such + * code was compiled to *not* perform PCCount-based profiling), so a brief + * performance hit to code execution can be expected after calling this. + */ +extern JS_PUBLIC_API void StartPCCountProfiling(JSContext* cx); + +/** + * Stop PCCount-based profiling if it has been started. + * + * Internally, this accumulates PCCount profiling results into an array of + * (script, script count info) for future consumption. If accumulation fails, + * this array will just be empty. + * + * This also discard all active JIT code (as such code was compiled to perform + * PCCount-based profiling), so a brief performance hit to code execution can be + * expected after calling this. + */ +extern JS_PUBLIC_API void StopPCCountProfiling(JSContext* cx); + +/** + * Get a count of all scripts for which PCCount profiling data was accumulated, + * after PCCount profiling has been stopped. + * + * As noted above, if an internal error occurred when profiling was stopped, + * this function will return 0. + */ +extern JS_PUBLIC_API size_t GetPCCountScriptCount(JSContext* cx); + +/** + * Get a JSON string summarizing PCCount data for the given script, by index + * within the internal array computed when PCCount profiling was stopped, of + * length indicated by |JS::GetPCCountScriptCount|. + * + * The JSON string will encode an object of this form: + * + * { + * "file": filename for the script, + * "line": line number within the script, + * + * // OPTIONAL: only if this script is a function + * "name": function name + * + * "totals": + * { + * "interp": sum of execution counts at all bytecode locations, + * "ion": sum of Ion activity counts, + * } + * } + * + * There is no inherent ordering to the (script, script count info) pairs within + * the array. Callers generally should expect to call this function in a loop + * to get summaries for all executed scripts. + */ +extern JS_PUBLIC_API JSString* GetPCCountScriptSummary(JSContext* cx, + size_t script); + +/** + * Get a JSON string encoding detailed PCCount data for the given script, by + * index within the internal array computed when PCCount profiling was stopped, + * of length indicated by |JS::GetPCCountScriptCount|. + * + * The JSON string will encode an object of this form: + * + * { + * "text": a string containg (possibly decompiled) source of the script, + * "line": line number within the script, + * + * "opcodes": + * [ + * // array elements of this form, corresponding to the script's + * // bytecodes + * { + * "id": offset of bytecode within script + * "line": line number for bytecode, + * "name": the name of the bytecode in question, + * "text": text of the expression being evaluated, + * "counts": + * { + * // OPTIONAL: only if the count is nonzero + * "interp": count of times executed, + * }, + * ], + * + * // OPTIONAL: only if the script is executed under Ion + * "ion": + * [ + * // array of elements of this form, corresponding to Ion basic blocks + * { + * "id": Ion block id, + * "offset": Ion block offset, + * "successors": + * [ + * // list of Ion block ids from which execution may proceed after + * // this one + * ], + * "hits": count of times this block was hit during execution, + * "code": a string containing the code in this Ion basic block, + * } + * ], + * } + * + * There is no inherent ordering to the (script, script count info) pairs within + * the array. Callers generally should expect to call this function in a loop + * to get summaries for all executed scripts. + */ +extern JS_PUBLIC_API JSString* GetPCCountScriptContents(JSContext* cx, + size_t script); + +/** + * Purge all accumulated PCCount profiling data, particularly the internal array + * that |JS::GetPCCountScript{Count,Summary,Contents}| exposes -- and all that + * array's references to previously-executed scripts. + */ +extern JS_PUBLIC_API void PurgePCCounts(JSContext* cx); + +} // namespace JS + +#endif // js_experimental_PCCountProfiling_h |