From: Russ Cox Date: Wed, 13 Dec 2017 16:49:26 +0000 (-0500) Subject: sync: document when and when not to use Map X-Git-Tag: go1.10beta2~53 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=3f150934e274f9ce167e1ed565fb3e60b8ea8223;p=gostls13.git sync: document when and when not to use Map Fixes #21587. Change-Id: I47eb181d65da67a3b530c7f8acac9c0c619ea474 Reviewed-on: https://go-review.googlesource.com/83796 Run-TryBot: Russ Cox Reviewed-by: Bryan Mills Reviewed-by: Rob Pike Reviewed-by: Brad Fitzpatrick --- diff --git a/src/sync/map.go b/src/sync/map.go index 083f4a563f..c4a0dc4194 100644 --- a/src/sync/map.go +++ b/src/sync/map.go @@ -9,20 +9,21 @@ import ( "unsafe" ) -// 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 like a Go map[interface{}]interface{} but is safe for concurrent use +// by multiple goroutines without additional locking or coordination. +// Loads, stores, and deletes run in amortized constant time. // -// 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. +// The Map type is specialized. Most code should use a plain Go map instead, +// with separate locking or coordination, for better type safety and to make it +// easier to maintain other invariants along with the map content. // -// 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 Map type is optimized for two common use cases: (1) when the entry for a given +// key is only ever written once but read many times, as in caches that only grow, +// or (2) when multiple goroutines read, write, and overwrite entries for disjoint +// sets of keys. In these two cases, use of a Map may significantly reduce lock +// contention compared to a Go map paired with a separate Mutex or RWMutex. // -// The zero Map is valid and empty. -// -// A Map must not be copied after first use. +// The zero Map is empty and ready for use. A Map must not be copied after first use. type Map struct { mu Mutex