Initial GetSample implementation.

include/v8-sampler.h

Index: include/v8-sampler.h
diff --git a/include/v8-sampler.h b/include/v8-sampler.h
new file mode 100644
index 0000000000000000000000000000000000000000..14fe51306cdfd2990838cb2526f514526c97c4da
--- /dev/null
+++ b/include/v8-sampler.h
@@ -0,0 +1,59 @@
+// Copyright 2014 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.
+
+#ifndef V8_V8_SAMPLER_H_
+#define V8_V8_SAMPLER_H_
+
+#include "v8.h"
+
+/**
+ * Sampler API for the V8 JavaScript engine.
+ * The API to be consumed by any code which
+ * wants to build a sampling profiler for v8.
+ */
+namespace v8 {
+  typedef unsigned char* Address;

[Benedikt Meurer, 2014/08/14 04:20:23]

We don't need this typedef at all. Just use const void* for pc values.

[gholap, 2014/08/15 17:54:13]

As I mentioned in the reply to your earlier comment, as we are subclassing
TickSample from Sample, we need the stack to be const char* for the code to even
compile. Let's discuss this on a hangout?

[Benedikt Meurer, 2014/08/18 04:22:03]

Got it. But please add a TODO to the typedef, that this should become const
void* at some point. (it's unsigned char* in the public API because of some
implementation detail)

[gholap, 2014/08/18 19:51:59]

Acknowledged.

+
+/**
+ * A collected sample contains,
+ * - state       : The state of the VM at the time of collecting the sample.
+ * - stack       : An array of addresses.
+ *                 One address per stack frame.
+ *                 The address is the instruction pointer,
+ *                 pointing to the instruction which led to the
+ *                 creation of the stack frame.
+ *                 (for example, a function call)
+ * - frames_count: Number of stack frames that were captured.
+ *                 That is, stack[frames_count+i] might contain meaningless
+ *                 addresses for any i >= 0.
+ */
+struct Sample {
+  Sample()
+      : state(OTHER),
+        frames_count(0) {}
+  static const unsigned kMaxFramesCountLog2 = 8;
+  static const unsigned kMaxFramesCount = (1 << kMaxFramesCountLog2) - 1;
+
+  StateTag state;                               // The state of the VM.
+  Address stack[kMaxFramesCount];               // Call stack.
+  unsigned frames_count : kMaxFramesCountLog2;  // Number of captured frames.
+};
+
+/**
+ * Interface for collecting execution stack samples.
+ */
+class V8_EXPORT Sampler {
+ public:
+  /**
+   * Obtain a sample from the isolate.
+   * Updates the sample pointer with the newly obtained
+   * sampling information.
+   * On success, returns the sample pointer.
+   * On failure, returns NULL.
+   */
+  static Sample* GetSample(Isolate* isolate,
+                           Sample* sample);
+};
+}  // namespace v8
+#endif  // V8_V8_SAMPLER_H_