snapshot of https://github.com/uber-go/guide.git (master, 2026-09-15; blobs > 131072B omitted)

src/atomic.md

@@ -0,0 +1,57 @@
+# Use go.uber.org/atomic
+
+Atomic operations with the [sync/atomic] package operate on the raw types
+(`int32`, `int64`, etc.) so it is easy to forget to use the atomic operation to
+read or modify the variables.
+
+[go.uber.org/atomic] adds type safety to these operations by hiding the
+underlying type. Additionally, it includes a convenient `atomic.Bool` type.
+
+  [go.uber.org/atomic]: https://pkg.go.dev/go.uber.org/atomic
+  [sync/atomic]: https://pkg.go.dev/sync/atomic
+
+<table>
+<thead><tr><th>Bad</th><th>Good</th></tr></thead>
+<tbody>
+<tr><td>
+
+```go
+type foo struct {
+  running int32  // atomic
+}
+
+func (f *foo) start() {
+  if atomic.SwapInt32(&f.running, 1) == 1 {
+     // already running…
+     return
+  }
+  // start the Foo
+}
+
+func (f *foo) isRunning() bool {
+  return f.running == 1  // race!
+}
+```
+
+</td><td>
+
+```go
+type foo struct {
+  running atomic.Bool
+}
+
+func (f *foo) start() {
+  if f.running.Swap(true) {
+     // already running…
+     return
+  }
+  // start the Foo
+}
+
+func (f *foo) isRunning() bool {
+  return f.running.Load()
+}
+```
+
+</td></tr>
+</tbody></table>