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