From: Austin Clements Date: Wed, 11 Jul 2018 13:02:46 +0000 (-0400) Subject: runtime: document philosophy behind runtime atomic usage X-Git-Tag: go1.11beta2~144 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=9300d223a3986b4419372bcd58c6cce7c845e8ae;p=gostls13.git runtime: document philosophy behind runtime atomic usage Based on Dmitry Vyukov's comments in CL 65210. Change-Id: I5dce7286b0d180cd43cad3aaf70f537fafcda588 Reviewed-on: https://go-review.googlesource.com/123275 Reviewed-by: Ian Lance Taylor Reviewed-by: Rick Hudson Reviewed-by: Dmitry Vyukov --- diff --git a/src/runtime/HACKING.md b/src/runtime/HACKING.md index 0b390c34d9..72ba61970b 100644 --- a/src/runtime/HACKING.md +++ b/src/runtime/HACKING.md @@ -135,6 +135,47 @@ In summary, parkYNN +Atomics +======= + +The runtime uses its own atomics package at `runtime/internal/atomic`. +This corresponds to `sync/atomic`, but functions have different names +for historical reasons and there are a few additional functions needed +by the runtime. + +In general, we think hard about the uses of atomics in the runtime and +try to avoid unnecessary atomic operations. If access to a variable is +sometimes protected by another synchronization mechanism, the +already-protected accesses generally don't need to be atomic. There +are several reasons for this: + +1. Using non-atomic or atomic access where appropriate makes the code + more self-documenting. Atomic access to a variable implies there's + somewhere else that may concurrently access the variable. + +2. Non-atomic access allows for automatic race detection. The runtime + doesn't currently have a race detector, but it may in the future. + Atomic access defeats the race detector, while non-atomic access + allows the race detector to check your assumptions. + +3. Non-atomic access may improve performance. + +Of course, any non-atomic access to a shared variable should be +documented to explain how that access is protected. + +Some common patterns that mix atomic and non-atomic access are: + +* Read-mostly variables where updates are protected by a lock. Within + the locked region, reads do not need to be atomic, but the write + does. Outside the locked region, reads need to be atomic. + +* Reads that only happen during STW, where no writes can happen during + STW, do not need to be atomic. + +That said, the advice from the Go memory model stands: "Don't be +[too] clever." The performance of the runtime matters, but its +robustness matters more. + Unmanaged memory ================