From: Austin Clements <austin@google.com>
Date: Mon, 26 Sep 2016 17:10:41 +0000 (-0400)
Subject: runtime: document bmap.tophash
X-Git-Tag: go1.8beta1~1066
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=bf776a988bf6fe82cbef5cfc954f33d127c5172c;p=gostls13.git

runtime: document bmap.tophash

In particular, it wasn't obvious that some values are special (unless
you also found those special values), so document that it isn't
necessarily a hash value.

Change-Id: Iff292822b44408239e26cd882dc07be6df2c1d38
Reviewed-on: https://go-review.googlesource.com/30143
Run-TryBot: Austin Clements <austin@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
---

diff --git a/src/runtime/hashmap.go b/src/runtime/hashmap.go
index e15926b05a..ab99d24c35 100644
--- a/src/runtime/hashmap.go
+++ b/src/runtime/hashmap.go
@@ -130,6 +130,9 @@ type hmap struct {
 
 // A bucket for a Go map.
 type bmap struct {
+	// tophash generally contains the top byte of the hash value
+	// for each key in this bucket. If tophash[0] < minTopHash,
+	// tophash[0] is a bucket evacuation state instead.
 	tophash [bucketCnt]uint8
 	// Followed by bucketCnt keys and then bucketCnt values.
 	// NOTE: packing all the keys together and then all the values together makes the
@@ -1079,6 +1082,8 @@ func evacuate(t *maptype, h *hmap, oldbucket uintptr) {
 		// Unlink the overflow buckets & clear key/value to help GC.
 		if h.flags&oldIterator == 0 {
 			b = (*bmap)(add(h.oldbuckets, oldbucket*uintptr(t.bucketsize)))
+			// Preserve b.tophash because the evacuation
+			// state is maintained there.
 			memclr(add(unsafe.Pointer(b), dataOffset), uintptr(t.bucketsize)-dataOffset)
 		}
 	}