Change to BucketStats and Bucket.Stats().

This commit pluralizes the BucketStat type to be BucketStats. This makes it
more consistent with the other Stats() calls. This commit also changes the
return type to a struct instead of a pointer.

Finally, this commit adds documentation to the fields of BucketStats.

bucket.go

@@ -329,8 +329,8 @@ func (b *Bucket) ForEach(fn func(k, v []byte) error) error {
 }
 
 // Stat returns stats on a bucket.
-func (b *Bucket) Stat() *BucketStat {
-	s := &BucketStat{}
+func (b *Bucket) Stats() BucketStats {
+	var s BucketStats
 	pageSize := b.tx.db.pageSize
 	b.tx.forEachPage(b.root, 0, func(p *page, depth int) {
 		if (p.flags & leafPageFlag) != 0 {
@@ -515,16 +515,21 @@ func (b *Bucket) pageNode(id pgid) (*page, *node) {
 	return b.tx.page(id), nil
 }
 
-// BucketStat represents stats on a bucket such as branch pages and leaf pages.
-type BucketStat struct {
-	BranchPageN     int
-	BranchOverflowN int
-	LeafPageN       int
-	LeafOverflowN   int
-	KeyN            int
-	Depth           int
-	BranchAlloc     int
-	BranchInuse     int
-	LeafAlloc       int
-	LeafInuse       int
+// BucketStats records statistics about resources used by a bucket.
+type BucketStats struct {
+	// Page count statistics.
+	BranchPageN     int // number of logical branch pages
+	BranchOverflowN int // number of physical branch overflow pages
+	LeafPageN       int // number of logical leaf pages
+	LeafOverflowN   int // number of physical leaf overflow pages
+
+	// Tree statistics.
+	KeyN  int // number of keys/value pairs
+	Depth int // number of levels in B+tree
+
+	// Page size utilization.
+	BranchAlloc int // bytes allocated for physical branch pages
+	BranchInuse int // bytes actually used for branch data
+	LeafAlloc   int // bytes allocated for physical leaf pages
+	LeafInuse   int // bytes actually used for leaf data
 }

bucket_test.go

@@ -473,7 +473,7 @@ func TestBucket_Put_KeyTooLarge(t *testing.T) {
 }
 
 // Ensure a bucket can calculate stats.
-func TestBucket_Stat(t *testing.T) {
+func TestBucket_Stats(t *testing.T) {
 	withOpenDB(func(db *DB, path string) {
 		db.Update(func(tx *Tx) error {
 			// Add bucket with fewer keys but one big value.
@@ -490,19 +490,19 @@ func TestBucket_Stat(t *testing.T) {
 		mustCheck(db)
 		db.View(func(tx *Tx) error {
 			b := tx.Bucket([]byte("woojits"))
-			stat := b.Stat()
-			assert.Equal(t, stat.BranchPageN, 1)
-			assert.Equal(t, stat.BranchOverflowN, 0)
-			assert.Equal(t, stat.LeafPageN, 6)
-			assert.Equal(t, stat.LeafOverflowN, 2)
-			assert.Equal(t, stat.KeyN, 501)
-			assert.Equal(t, stat.Depth, 2)
+			stats := b.Stats()
+			assert.Equal(t, stats.BranchPageN, 1)
+			assert.Equal(t, stats.BranchOverflowN, 0)
+			assert.Equal(t, stats.LeafPageN, 6)
+			assert.Equal(t, stats.LeafOverflowN, 2)
+			assert.Equal(t, stats.KeyN, 501)
+			assert.Equal(t, stats.Depth, 2)
 			if os.Getpagesize() != 4096 {
 				// Incompatible page size
-				assert.Equal(t, stat.BranchInuse, 125)
-				assert.Equal(t, stat.BranchAlloc, 4096)
-				assert.Equal(t, stat.LeafInuse, 20908)
-				assert.Equal(t, stat.LeafAlloc, 32768)
+				assert.Equal(t, stats.BranchInuse, 125)
+				assert.Equal(t, stats.BranchAlloc, 4096)
+				assert.Equal(t, stats.LeafInuse, 20908)
+				assert.Equal(t, stats.LeafAlloc, 32768)
 			}
 			return nil
 		})
@@ -510,7 +510,7 @@ func TestBucket_Stat(t *testing.T) {
 }
 
 // Ensure a bucket can calculate stats.
-func TestBucket_Stat_Small(t *testing.T) {
+func TestBucket_Stats_Small(t *testing.T) {
 
 	withOpenDB(func(db *DB, path string) {
 		db.Update(func(tx *Tx) error {
@@ -524,19 +524,19 @@ func TestBucket_Stat_Small(t *testing.T) {
 		mustCheck(db)
 		db.View(func(tx *Tx) error {
 			b := tx.Bucket([]byte("whozawhats"))
-			stat := b.Stat()
-			assert.Equal(t, stat.BranchPageN, 0)
-			assert.Equal(t, stat.BranchOverflowN, 0)
-			assert.Equal(t, stat.LeafPageN, 1)
-			assert.Equal(t, stat.LeafOverflowN, 0)
-			assert.Equal(t, stat.KeyN, 1)
-			assert.Equal(t, stat.Depth, 1)
+			stats := b.Stats()
+			assert.Equal(t, stats.BranchPageN, 0)
+			assert.Equal(t, stats.BranchOverflowN, 0)
+			assert.Equal(t, stats.LeafPageN, 1)
+			assert.Equal(t, stats.LeafOverflowN, 0)
+			assert.Equal(t, stats.KeyN, 1)
+			assert.Equal(t, stats.Depth, 1)
 			if os.Getpagesize() != 4096 {
 				// Incompatible page size
-				assert.Equal(t, stat.BranchInuse, 0)
-				assert.Equal(t, stat.BranchAlloc, 0)
-				assert.Equal(t, stat.LeafInuse, 38)
-				assert.Equal(t, stat.LeafAlloc, 4096)
+				assert.Equal(t, stats.BranchInuse, 0)
+				assert.Equal(t, stats.BranchAlloc, 0)
+				assert.Equal(t, stats.LeafInuse, 38)
+				assert.Equal(t, stats.LeafAlloc, 4096)
 			}
 			return nil
 		})
@@ -544,7 +544,7 @@ func TestBucket_Stat_Small(t *testing.T) {
 }
 
 // Ensure a large bucket can calculate stats.
-func TestBucket_Stat_Large(t *testing.T) {
+func TestBucket_Stats_Large(t *testing.T) {
 	if testing.Short() {
 		t.Skip("skipping test in short mode.")
 	}
@@ -562,19 +562,19 @@ func TestBucket_Stat_Large(t *testing.T) {
 		mustCheck(db)
 		db.View(func(tx *Tx) error {
 			b := tx.Bucket([]byte("widgets"))
-			stat := b.Stat()
-			assert.Equal(t, stat.BranchPageN, 15)
-			assert.Equal(t, stat.BranchOverflowN, 0)
-			assert.Equal(t, stat.LeafPageN, 1281)
-			assert.Equal(t, stat.LeafOverflowN, 0)
-			assert.Equal(t, stat.KeyN, 100000)
-			assert.Equal(t, stat.Depth, 3)
+			stats := b.Stats()
+			assert.Equal(t, stats.BranchPageN, 15)
+			assert.Equal(t, stats.BranchOverflowN, 0)
+			assert.Equal(t, stats.LeafPageN, 1281)
+			assert.Equal(t, stats.LeafOverflowN, 0)
+			assert.Equal(t, stats.KeyN, 100000)
+			assert.Equal(t, stats.Depth, 3)
 			if os.Getpagesize() != 4096 {
 				// Incompatible page size
-				assert.Equal(t, stat.BranchInuse, 27289)
-				assert.Equal(t, stat.BranchAlloc, 61440)
-				assert.Equal(t, stat.LeafInuse, 2598276)
-				assert.Equal(t, stat.LeafAlloc, 5246976)
+				assert.Equal(t, stats.BranchInuse, 27289)
+				assert.Equal(t, stats.BranchAlloc, 61440)
+				assert.Equal(t, stats.LeafInuse, 2598276)
+				assert.Equal(t, stats.LeafAlloc, 5246976)
 			}
 			return nil
 		})