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..5bd970218973428cb375c13954433c31bfe23e97
--- /dev/null
+++ b/include/v8-sampler.h
@@ -0,0 +1,69 @@
+// 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 {
+  /* TODO(gholap): Find a better way of doing this? */
+  typedef unsigned char* Address;

[Benedikt Meurer, 2014/08/13 06:29:11]

I don't think we need this type at all. See below.

[gholap, 2014/08/13 21:09:21]

Yang suggested that we subclass the internal TickSample struct from the Sample
struct defined in here, that would address the flimsy and fragile nature of the
casting issue. On the other hand, that means we would need to keep the
Sample::stack as Address...

What would you suggest?

+
+/**
+ * VMState indicates what action the VM is performing during that state.
+ */
+enum VMState {
+  JS,              // Executing JavaScript.
+  GC,              // Garbage Collection.
+  COMPILER,        // Compiling JavaScript.
+  OTHER,
+  EXTERNAL,        // External call. (For example, a call into blink)
+  IDLE             // The VM is idle.

[Yang, 2014/08/12 14:21:35]

v8::internal::VMState scope still uses the StateTag in globals.h, which should
mirror this. Can we only have this one copy, or at least STATIC_ASSERT that this
is in sync?

[gholap, 2014/08/13 21:09:21]

Yes, I moved the internal StateTag from globals.h to v8.h and now that's the
only place now this enum exists. Let me know how that sounds.

+};
+
+/**
+ * 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 {
+  static const unsigned kMaxFramesCountLog2 = 8;
+  static const unsigned kMaxFramesCount = (1 << kMaxFramesCountLog2) - 1;
+
+  VMState state;                                // The state of the VM.
+  Address stack[kMaxFramesCount];               // Call stack.

[Benedikt Meurer, 2014/08/13 06:29:11]

Use const void* instead of Address.

[gholap, 2014/08/13 21:09:21]

Acknowledged.

+  unsigned frames_count : kMaxFramesCountLog2;  // Number of captured frames.

[Yang, 2014/08/12 14:21:36]

Casting between Sample and TickSample seems very fragile to me. Can we subclass
TickSample from Sample?

[gholap, 2014/08/13 21:09:21]

Done.

+};
+
+/**
+ * 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_