issue-466: Clarified stats output and comments for ExtractStats() and GetThreadStats()

git-svn-id: http://gperftools.googlecode.com/svn/trunk@188 6b5cf1ce-ec42-a296-1ba9-69fdba395a50

2 files changed, 16 insertions, 7 deletions

diff --git a/src/tcmalloc.cc b/src/tcmalloc.cc
index 9092687..af04e04 100644
--- a/src/tcmalloc.cc
+++ b/src/tcmalloc.cc
@@ -299,7 +299,10 @@ struct TCMallocStats {
   PageHeap::Stats pageheap;   // Stats from page heap
 };
 
-// Get stats into "r".  Also get per-size-class counts if class_count != NULL
+// Get stats into "r".  Also, if class_count != NULL, class_count[k]
+// will be set to the total number of objects of size class k in the
+// central cache, transfer cache, and per-thread caches. If small_spans
+// is non-NULL, it is filled.  Same for large_spans.
 static void ExtractStats(TCMallocStats* r, uint64_t* class_count,
                          PageHeap::SmallSpanStats* small_spans,
                          PageHeap::LargeSpanStats* large_spans) {
@@ -313,7 +316,12 @@ static void ExtractStats(TCMallocStats* r, uint64_t* class_count,
         Static::sizemap()->ByteSizeForClass(cl));
     r->central_bytes += (size * length) + cache_overhead;
     r->transfer_bytes += (size * tc_length);
-    if (class_count) class_count[cl] = length + tc_length;
+    if (class_count) {
+      // Sum the lengths of all per-class freelists, except the per-thread
+      // freelists, which get counted when we call GetThreadStats(), below.
+      class_count[cl] = length + tc_length;
+    }
+
   }
 
   // Add stats from per-thread heaps
@@ -402,7 +410,8 @@ static void DumpStats(TCMalloc_Printer* out, int level) {
 
   if (level >= 2) {
     out->printf("------------------------------------------------\n");
-    out->printf("Size class breakdown\n");
+    out->printf("Total size of freelists for per-thread caches,\n");
+    out->printf("transfer cache, and central cache, by size class\n");
     out->printf("------------------------------------------------\n");
     uint64_t cumulative = 0;
     for (int cl = 0; cl < kNumClasses; ++cl) {
diff --git a/src/thread_cache.h b/src/thread_cache.h
index 8644a4d..db18626 100644
--- a/src/thread_cache.h
+++ b/src/thread_cache.h
@@ -123,10 +123,10 @@ class ThreadCache {
   // Return the number of thread heaps in use.
   static inline int HeapsInUse();
 
-  // Writes to total_bytes the total number of bytes used by all thread heaps.
-  // class_count must be an array of size kNumClasses.  Writes the number of
-  // items on the corresponding freelist.  class_count may be NULL.
-  // The storage of both parameters must be zero intialized.
+  // Adds to *total_bytes the total number of bytes used by all thread heaps.
+  // Also, if class_count is not NULL, it must be an array of size kNumClasses,
+  // and this function will increment each element of class_count by the number
+  // of items in all thread-local freelists of the corresponding size class.
   // REQUIRES: Static::pageheap_lock is held.
   static void GetThreadStats(uint64_t* total_bytes, uint64_t* class_count);