Initial implementation of GetStackSample sampling profiler API.

include/v8.h

Index: include/v8.h
diff --git a/include/v8.h b/include/v8.h
index ec1941e6fd86eec42707e4d41011112961fe2109..1fe6bee30d1e90fa006dd8dd6b92695efcb8eb4f 100644
--- a/include/v8.h
+++ b/include/v8.h
@@ -1415,6 +1415,27 @@ class V8_EXPORT StackFrame {
 };
 
 
+// A StateTag represents a possible state of the VM.
+enum StateTag { JS, GC, COMPILER, OTHER, EXTERNAL, IDLE };
+
+
+// A RegisterState represents the current state of registers used
+// by the sampling profiler API.
+struct RegisterState {
+  RegisterState() : pc(NULL), sp(NULL), fp(NULL) {}
+  void* pc;  // Instruction pointer.
+  void* sp;  // Stack pointer.
+  void* fp;  // Frame pointer.
+};
+
+
+// The output structure filled up by GetStackSample API function.
+struct SampleInfo {
+  size_t frames_count;

[loislo, 2014/09/24 14:41:29]

Can we join together both output structures i.e. the array of frames and
SampleInfo?

The motivation: the embedder wouldn't be able to do a synchronous post
processing for these data because the restrictions for signal handler.
So with this API the embedder has to have two preallocated buffers. one for
frames and the other for SampleInfo with frames count and needs to keep them in
sync.

It could be done the old school way:

struct SampleInfo {
  StateTag vm_state;
  size_t frames_count;
  void* frames[1]; // the actual used size depends on frames_count.
}

[alph, 2014/09/24 14:57:39]

It would be quite difficult for the embedder to convert (without copying) from
SampleInfo if it chooses to store the data in a different format.
E.g. if frames are stored in one buffer and the rest is in another.

The current format seems to be more flexible, as it allows the embedder to store
frames wherever it wants.

+  StateTag vm_state;
+};
+
+
 /**
  * A JSON Parser.
  */
@@ -4548,6 +4569,21 @@ class V8_EXPORT Isolate {
   void GetHeapStatistics(HeapStatistics* heap_statistics);
 
   /**
+   * Get a call stack sample from the isolate.
+   * \param state Execution state.
+   * \param frames Caller allocated buffer to store stack frames.
+   * \param frames_limit Maximum number of frames to capture. The buffer must
+   *                     be large enough to hold the number of frames.
+   * \param sample_info The sample info is filled up by the function
+   *                    provides number of actual captured stack frames and
+   *                    the current VM state.
+   * \note GetStackSample should only be called when the JS thread is paused or
+   *       interrupted. Otherwise the behavior is undefined.
+   */
+  void GetStackSample(const RegisterState& state, void** frames,
+                      size_t frames_limit, SampleInfo* sample_info);
+
+  /**
    * Adjusts the amount of registered external memory. Used to give V8 an
    * indication of the amount of externally allocated memory that is kept alive
    * by JavaScript objects. V8 uses this to decide when to perform global