The lack of links to https://go.dev/ref/mem in the sync package
documentation makes it difficult to read for people who have no previous
knowledge of that page. This PR includes the links where needed.
Fixes #67891
Change-Id: I0e1344cc6d7b702f4cb2e55fe0fcee3eb089391a
GitHub-Last-Rev:
427cf58aaeaae2e4b060248dd592e5fe8c6b7df4
GitHub-Pull-Request: golang/go#67892
Reviewed-on: https://go-review.googlesource.com/c/go/+/591395
Reviewed-by: Michael Knyszek <mknyszek@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
// functions, are the atomic equivalents of "return *addr" and
// "*addr = val".
//
-// In the terminology of the Go memory model, if the effect of
+// In the terminology of [the Go memory model], if the effect of
// an atomic operation A is observed by atomic operation B,
// then A “synchronizes before” B.
// Additionally, all the atomic operations executed in a program
// behave as though executed in some sequentially consistent order.
// This definition provides the same semantics as
// C++'s sequentially consistent atomics and Java's volatile variables.
+//
+// [the Go memory model]: https://go.dev/ref/mem
package atomic
import (
//
// A Cond must not be copied after first use.
//
-// In the terminology of the Go memory model, Cond arranges that
+// In the terminology of [the Go memory model], Cond arranges that
// a call to [Cond.Broadcast] or [Cond.Signal] “synchronizes before” any Wait call
// that it unblocks.
//
// advanced concurrency patterns], as well as [Bryan Mills's talk on concurrency
// patterns].
//
+// [the Go memory model]: https://go.dev/ref/mem
// [Roberto Clapis's series on advanced concurrency patterns]: https://blogtitle.github.io/categories/concurrency/
// [Bryan Mills's talk on concurrency patterns]: https://drive.google.com/file/d/1nPdvhB0PutEJzdCq5ms6UI58dp50fcAN/view
type Cond struct {
//
// The zero Map is empty and ready for use. A Map must not be copied after first use.
//
-// In the terminology of the Go memory model, Map arranges that a write operation
+// In the terminology of [the Go memory model], Map arranges that a write operation
// “synchronizes before” any read operation that observes the effect of the write, where
// read and write operations are defined as follows.
// [Map.Load], [Map.LoadAndDelete], [Map.LoadOrStore], [Map.Swap], [Map.CompareAndSwap],
// [Map.LoadOrStore] is a write operation when it returns loaded set to false;
// [Map.CompareAndSwap] is a write operation when it returns swapped set to true;
// and [Map.CompareAndDelete] is a write operation when it returns deleted set to true.
+//
+// [the Go memory model]: https://go.dev/ref/mem
type Map struct {
mu Mutex
//
// A Mutex must not be copied after first use.
//
-// In the terminology of the Go memory model,
+// In the terminology of [the Go memory model],
// the n'th call to [Mutex.Unlock] “synchronizes before” the m'th call to [Mutex.Lock]
// for any n < m.
// A successful call to [Mutex.TryLock] is equivalent to a call to Lock.
// A failed call to TryLock does not establish any “synchronizes before”
// relation at all.
+//
+// [the Go memory model]: https://go.dev/ref/mem
type Mutex struct {
state int32
sema uint32
//
// A Once must not be copied after first use.
//
-// In the terminology of the Go memory model,
+// In the terminology of [the Go memory model],
// the return from f “synchronizes before”
// the return from any call of once.Do(f).
+//
+// [the Go memory model]: https://go.dev/ref/mem
type Once struct {
// done indicates whether the action has been performed.
// It is first in the struct because it is used in the hot path.
//
// A Pool must not be copied after first use.
//
-// In the terminology of the Go memory model, a call to Put(x) “synchronizes before”
+// In the terminology of [the Go memory model], a call to Put(x) “synchronizes before”
// a call to [Pool.Get] returning that same value x.
// Similarly, a call to New returning x “synchronizes before”
// a call to Get returning that same value x.
+//
+// [the Go memory model]: https://go.dev/ref/mem
type Pool struct {
noCopy noCopy
// the lock eventually becomes available to the writer.
// Note that this prohibits recursive read-locking.
//
-// In the terminology of the Go memory model,
+// In the terminology of [the Go memory model],
// the n'th call to [RWMutex.Unlock] “synchronizes before” the m'th call to Lock
// for any n < m, just as for [Mutex].
// For any call to RLock, there exists an n such that
// the n'th call to Unlock “synchronizes before” that call to RLock,
// and the corresponding call to [RWMutex.RUnlock] “synchronizes before”
// the n+1'th call to Lock.
+//
+// [the Go memory model]: https://go.dev/ref/mem
type RWMutex struct {
w Mutex // held if there are pending writers
writerSem uint32 // semaphore for writers to wait for completing readers
//
// A WaitGroup must not be copied after first use.
//
-// In the terminology of the Go memory model, a call to [WaitGroup.Done]
+// In the terminology of [the Go memory model], a call to [WaitGroup.Done]
// “synchronizes before” the return of any Wait call that it unblocks.
+//
+// [the Go memory model]: https://go.dev/ref/mem
type WaitGroup struct {
noCopy noCopy