Initial implementation of GetStackSample sampling profiler API.

include/v8.h

 // Copyright 2012 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 /** \mainpage V8 API Reference Guide
  *
  * V8 is Google's open source JavaScript engine.
  *
  * This set of documents provides reference material generated from the
  * V8 header file, include/v8.h.
@@ skipping 1397 matching lines @@
   bool IsEval() const;
 
   /**
    * Returns whether or not the associated function is called as a
    * constructor via "new".
    */
   bool IsConstructor() const;
 };
 
 
+// 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.
  */
 class V8_EXPORT JSON {
  public:
   /**
    * Tries to parse the string |json_string| and returns it as value if
    * successful.
    *
    * \param json_string The string to parse.
@@ skipping 3113 matching lines @@
    * are in the range of 0 - GetNumberOfDataSlots() - 1.
    */
   V8_INLINE static uint32_t GetNumberOfDataSlots();
 
   /**
    * Get statistics about the heap memory usage.
    */
   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
    * garbage collections. Registering externally allocated memory will trigger
    * global garbage collections more often than it would otherwise in an attempt
    * to garbage collect the JavaScript objects that keep the externally
    * allocated memory alive.
    *
    * \param change_in_bytes the change in externally allocated memory that is
    *   kept alive by JavaScript objects.
@@ skipping 2388 matching lines @@
  */
 
 
 }  // namespace v8
 
 
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_