runtime: document concurrency of mheap.spans

We use lock-free reads from mheap.spans, but the safety of these is
somewhat subtle. Document this.

Change-Id: I928c893232176135308e38bed788d5f84ff11533
Reviewed-on: https://go-review.googlesource.com/54310
Reviewed-by: Rick Hudson <rlh@golang.org>

diff --git a/src/runtime/mheap.go b/src/runtime/mheap.go
index 893587e5d2243a0a99f8a131853a500c7d9a5d3f..bf4112576469afa03de9a5e45147b23b48e96ef6 100644 (file)
--- a/src/runtime/mheap.go
+++ b/src/runtime/mheap.go
@@ -56,6 +56,12 @@ type mheap struct {
        // Internal pages map to an arbitrary span.
        // For pages that have never been allocated, spans entries are nil.
        //
+       // Modifications are protected by mheap.lock. Reads can be
+       // performed without locking, but ONLY from indexes that are
+       // known to contain in-use or stack spans. This means there
+       // must not be a safe-point between establishing that an
+       // address is live and looking it up in the spans array.
+       //
        // This is backed by a reserved region of the address space so
        // it can grow without moving. The memory up to len(spans) is
        // mapped. cap(spans) indicates the total reserved memory.