--- old/src/hotspot/share/runtime/heapMonitoring.hpp	2017-09-22 13:33:07.905845242 -0700
+++ new/src/hotspot/share/runtime/heapMonitoring.hpp	2017-09-22 13:33:07.557846389 -0700
@@ -68,24 +68,34 @@
   }
 
  public:
+  /*
+   * General note: currently none of these methods are deemed thread-safe.
+   */
+
+  // First method called by user to start the profiler:
+  //   - Note: the lower the monitoring rate, the higher the overhead incurred.
+  static void initialize_profiling(jint monitoring_rate, jint max_storage);
+
+  // Pick the next sample for a given size_t pointer using a geometric variable
+  // with specified mean. The specified mean is provided via the
+  // initialize_profiling method.
   static void pick_next_sample(size_t *ptr);
 
+  // Get live/garbage traces and provide a method to release the traces.
   static void get_live_traces(jvmtiStackTraces* stack_traces);
-  static void get_sampling_statistics(jvmtiHeapSamplingStats* stats);
   static void get_garbage_traces(jvmtiStackTraces* stack_traces);
   static void get_frequent_garbage_traces(jvmtiStackTraces* stack_traces);
   static void release_traces(jvmtiStackTraces *trace_info);
-  static void initialize_profiling(jint monitoring_rate, jint max_storage);
+
+  static void get_sampling_statistics(jvmtiHeapSamplingStats* stats);
   static void stop_profiling();
+
+  // Is the profiler initialized and where is the address to the initialized
+  // boolean.
   static bool initialized();
   static bool *initialized_address();
 
-  // Called when o is allocated, called by interpreter and C1.
-  static void object_alloc_unsized(oopDesc* o);
-  static void object_alloc(oopDesc* o, intx byte_size);
-
-  // Called when o is allocated from C2 directly,
-  // we know the thread, and we have done the sampling.
+  // Called when o is to be sampled from a given thread and a given size.
   static void object_alloc_do_sample(Thread *t, oopDesc *o, intx size_in_bytes);
 
   // Called to clean up oops that have been saved by our sampling function,