StackSamplingProfiler clean up

base/profiler/stack_sampling_profiler.h

Index: base/profiler/stack_sampling_profiler.h
diff --git a/base/profiler/stack_sampling_profiler.h b/base/profiler/stack_sampling_profiler.h
index 60faa51b780476ad3cf791f1482c2b393d2d3f55..9fd3d8d173804871be8c59d1ec7e8f8f09b147d4 100644
--- a/base/profiler/stack_sampling_profiler.h
+++ b/base/profiler/stack_sampling_profiler.h
@@ -23,7 +23,7 @@ namespace base {
 // executing. This information is used in aggregate by UMA to identify hot
 // and/or janky code paths.
 //
-// Sample StackStackSamplingProfiler usage:
+// Sample StackSamplingProfiler usage:
 //
 //   // Create and customize params as desired.
 //   base::StackStackSamplingProfiler::SamplingParams params;
@@ -33,7 +33,7 @@ namespace base {
 //
 //   // To process the profiles within Chrome rather than via UMA, set a custom
 //   // completed callback:
-//   base::Callback<void(const std::vector<Profile>&)>
+//   base::StackStackSamplingProfiler::CompletedCallback
 //       thread_safe_callback = ...;
 //   profiler.SetCustomCompletedCallback(thread_safe_callback);
 //
@@ -41,13 +41,24 @@ namespace base {
 //   // ... work being done on the target thread here ...
 //   profiler.Stop();  // optional, stops collection before complete per params
 //
+// The default SamplingParams causes stacks to be recorded in a single burst at
+// a 10Hz interval for a total of 30 seconds. All of these parameters may be
+// altered as desired.
+//
 // When all profiles are complete or the profiler is stopped, if the custom
-// completed callback was set it will be called from the profiler thread with
-// the completed profiles. If no callback was set, the profiles are stored
-// internally and retrieved for UMA through
-// GetPendingProfiles(). GetPendingProfiles() should never be called by other
-// code; to retrieve profiles for in-process processing, set a completed
-// callback.
+// completed callback was set it is called from the profiler thread with the
+// completed profiles. A profile is considered complete if all requested samples
+// were recorded for the profile (i.e. it was not stopped prematurely). If no
+// callback was set, the completed profiles are stored internally and retrieved
+// for UMA through GetPendingProfiles().  GetPendingProfiles() should never be
+// called by other code; to retrieve profiles for in-process processing, set a
+// completed callback.
+//
+// The results of the profiling are passed to the completed callback and consist
+// of a vector of Profiles. Each Profile corresponds to a burst as specified in
+// SamplingParams and contains a set of Samples and Modules. One Sample
+// corresponds to a single recorded stack, and the Modules record those modules
+// associated with the recorded stack frames.
 class BASE_EXPORT StackSamplingProfiler {
  public:
   // Module represents the module (DLL or exe) corresponding to a stack frame.
@@ -71,14 +82,17 @@ class BASE_EXPORT StackSamplingProfiler {
 
   // Frame represents an individual sampled stack frame with module information.
   struct Frame {
-    Frame();
+    Frame(const void* instruction_pointer, size_t module_index);
     ~Frame();
 
     // The sampled instruction pointer within the function.
     const void* instruction_pointer;
-    // Index of the module in the array of modules. We don't represent module
-    // state directly here to save space.
-    int module_index;
+    // Index of the module in Profile::modules. We don't represent module state
+    // directly here to save space.
+    size_t module_index;
+
+    // Identifies a unknown module.
+    static const size_t kUnknownModuleIndex = static_cast<size_t>(-1);
   };
 
   // Sample represents a set of stack frames.
@@ -106,19 +120,20 @@ class BASE_EXPORT StackSamplingProfiler {
    public:
     virtual ~NativeStackSampler();
 
-    // Create a stack sampler that records samples for |thread_handle|. Returns
+    // Creates a stack sampler that records samples for |thread_handle|. Returns
     // null if this platform does not support stack sampling.
     static scoped_ptr<NativeStackSampler> Create(PlatformThreadId thread_id);
 
-    // Notify the sampler that we're starting to record a new profile. This
-    // function is called on the SamplingThread.
+    // Notifies the sampler that we're starting to record a new profile. This
+    // function is called on the thread used for sampling.
     virtual void ProfileRecordingStarting(Profile* profile) = 0;
 
-    // Record a stack sample. This function is called on the SamplingThread.
+    // Records a stack sample. This function is called on the thread used for
+    // sampling.
     virtual void RecordStackSample(Sample* sample) = 0;
 
-    // Notify the sampler that we've stopped recording the current profile. This
-    // function is called on the SamplingThread.
+    // Notifies the sampler that we've stopped recording the current
+    // profile. This function is called on the thread used for sampling.
     virtual void ProfileRecordingStopped() = 0;
 
    protected:
@@ -142,27 +157,30 @@ class BASE_EXPORT StackSamplingProfiler {
     // Number of samples to record per burst. Defaults to 300.
     int samples_per_burst;
     // Interval between samples during a sampling burst. This is the desired
-    // duration from the start of one burst to the start of the next
-    // burst. Defaults to 100ms.
+    // duration from the start of one sample to the start of the next
+    // sample. Defaults to 100ms.
     TimeDelta sampling_interval;
     // True if sample ordering is important and should be preserved if and when
     // this profile is compressed and processed. Defaults to false.
     bool preserve_sample_ordering;
   };
 
+  using CompletedCallback = Callback<void(const std::vector<Profile>&)>;
+
   StackSamplingProfiler(PlatformThreadId thread_id,
                         const SamplingParams& params);
   ~StackSamplingProfiler();
 
   // Initializes the profiler and starts sampling.
   void Start();
+
   // Stops the profiler and any ongoing sampling. Calling this function is
-  // optional; if not invoked profiling will terminate when all the profiling
-  // bursts specified in the SamplingParams are completed.
+  // optional; if not invoked profiling terminates when all the profiling bursts
+  // specified in the SamplingParams are completed.
   void Stop();
 
-  // Gets the pending profiles into *|profiles| and clears the internal
-  // storage. This function is thread safe.
+  // Moves all pending profiles from internal storage to |profiles|. This
+  // function is thread safe.
   //
   // ***This is intended for use only by UMA.*** Callers who want to process the
   // collected profiles should use SetCustomCompletedCallback.
@@ -170,12 +188,15 @@ class BASE_EXPORT StackSamplingProfiler {
 
   // By default, collected profiles are stored internally and can be retrieved
   // by GetPendingProfiles. If a callback is provided via this function,
-  // however, it will be called with the collected profiles instead. Note that
-  // this call to the callback occurs *on the profiler thread*.
-  void SetCustomCompletedCallback(
-      Callback<void(const std::vector<Profile>&)> callback);
+  // however, it is called with the collected profiles instead. Note that the
+  // call to the callback occurs *on the profiler thread*.
+  void set_custom_completed_callback(CompletedCallback callback) {
+    custom_completed_callback_ = callback;
+  }
 
  private:
+  // SamplingThread is a separate thread used to suspend and sample stacks from
+  // the target thread.
   class SamplingThread;
   struct SamplingThreadDeleter {
     void operator() (SamplingThread* thread) const;
@@ -189,7 +210,7 @@ class BASE_EXPORT StackSamplingProfiler {
   scoped_ptr<SamplingThread, SamplingThreadDeleter> sampling_thread_;
   scoped_ptr<NativeStackSampler> native_sampler_;
 
-  Callback<void(const std::vector<Profile>&)> custom_completed_callback_;
+  CompletedCallback custom_completed_callback_;
 
   DISALLOW_COPY_AND_ASSIGN(StackSamplingProfiler);
 };
@@ -204,3 +225,4 @@ BASE_EXPORT bool operator<(const StackSamplingProfiler::Frame& a,
 }  // namespace base
 
 #endif  // BASE_PROFILER_STACK_SAMPLING_PROFILER_H_
+