summaryrefslogtreecommitdiffstats
path: root/js/public/experimental/PCCountProfiling.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--js/public/experimental/PCCountProfiling.h162
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