sync: update Map documentation with usage rule of thumb

As per bcmills’s lightning talk at GopherCon 2017:
https://github.com/gophercon/2017-talks/tree/master/lightningtalks/BryanCMills-AnOverviewOfSyncMap

Change-Id: I12dd0daa608af175d110298780f32c6dc5e1e0a0
Reviewed-on: https://go-review.googlesource.com/50310
Reviewed-by: Bryan Mills <bcmills@google.com>

1 files changed, 9 insertions, 0 deletions

diff --git a/src/sync/map.go b/src/sync/map.go
index 1238368d38..c3c2d1cc86 100644
--- a/src/sync/map.go
+++ b/src/sync/map.go
@@ -12,6 +12,15 @@ import (
 // Map is a concurrent map with amortized-constant-time loads, stores, and deletes.
 // It is safe for multiple goroutines to call a Map's methods concurrently.
 //
+// Map is designed to reduce cache contention in the Go standard library.
+// It is optimized for use in concurrent loops with keys that are stable
+// over time, and either few steady-state stores, or stores localized to
+// one goroutine per key.
+//
+// For use cases that do not share these attributes, it will likely have
+// comparable or worse performance and worse type safety than an ordinary
+// map paired with a read-write mutex.
+//
 // The zero Map is valid and empty.
 //
 // A Map must not be copied after first use.