Why does incrementing an atomic.Int64 only while it stays under a cap need CompareAndSwap rather than Add?

## The gap that `Add` cannot close `atomic.Int64.Add(delta)` is a single indivisible read-modify-write that returns the new value. What it is not, is *conditional*. There is no argument that says "apply this only if the result stays below 100", and there is no way to undo it inside the same operation. So the obvious code is wrong: ```go if n.Load() < limit { n.Add(1) // WRONG: the value may have changed since Load } ``` Both lines are individually atomic, and the sequence of the two is not. This is a **check-then-act** race. With `limit` at 100 and the counter at 99, twenty goroutines can all execute the `Load`, all see 99, all pass the check, and all call `Add(1)`. The counter lands at 119. Nothing is torn or corrupted — every operation did exactly what it promised — but the invariant the code was written to enforce is broken. The race detector will not report this, because there is no data race: every access went through an atomic operation. ## What compare-and-swap actually promises `func (x *Int64) CompareAndSwap(old, new int64) (swapped bool)` does one indivisible thing: if the current value is exactly `old`, replace it with `new` and report `true`; otherwise change nothing and report `false`. The comparison and the conditional write cannot be separated, which is precisely what the check-then-act version lacked. The false result is information, not an error. It means "the value moved under you since you read it", so any decision you based on the old value has to be made again against the new one. ## The retry loop ```go func tryAcquire(n *atomic.Int64, limit int64) bool { for { cur := n.Load() if cur >= limit { return false // at the cap: give up, do not retry } if n.CompareAndSwap(cur, cur+1) { return true } // somebody else changed it; re-read and decide again } } ``` Four details are worth naming. **The re-read is inside the loop.** A common bug is hoisting `cur := n.Load()` above the `for` and retrying `CompareAndSwap(cur, cur+1)` with the same stale `cur`. That can only ever fail again, or — worse — succeed later against a value that happens to have come back to `cur`, silently clobbering the updates in between. **The decision is inside the loop too.** The whole point is that the cap check must be re-evaluated against the fresh value, not just the arithmetic. **Failure is not an error path.** A `false` return from `CompareAndSwap` under contention is normal and expected; it means progress was made, just not by this goroutine. The loop is lock-free in the technical sense: some goroutine always makes progress, though no individual goroutine is guaranteed to finish in a bounded number of iterations. **Both branches leave the loop deliberately.** `return false` is the "at the cap" answer; `return true` is the "reservation taken" answer. Only the contention case loops. ## The reserve-and-refund alternative There is a second idiom worth knowing, because it appears often in admission code: ```go if n.Add(1) > limit { n.Add(-1) return false } return true ``` This uses `Add`'s return value to reserve first and give the slot back if it turns out to be over the cap. It is simpler and has no loop, but it is not equivalent: the counter *transiently* exceeds the limit, so a concurrent reader calling `Load` can observe a value above the cap, and a strict cap on a real resource (open connections, in-flight requests reserved against a quota) would be momentarily violated. Choose it when the counter is advisory and the transient overshoot is harmless; choose the CAS loop when the cap is an invariant somebody depends on. ## Where the other methods fit `Swap(new)` writes unconditionally and returns the old value — that is how you take a batch of counted events and reset the counter to zero in one step, with no window in which an increment is dropped. `Store` is the unconditional write with no result at all. `CompareAndSwap` is the only one of the family that lets the *current value* participate in the decision, and it is available on the whole typed set — `atomic.Int32`, `atomic.Bool`, `atomic.Pointer[T]` and `atomic.Value` all carry it, with the same "only if unchanged" contract. The classic caveat about compare-and-swap on pointers — the value coming back to an earlier state between your read and your swap — is much less dangerous in Go than in a manually-managed language, because a pointer you still hold cannot have been freed and its address reused while you hold it. It is still a real hazard for CAS loops over values that legitimately cycle, so if a loop's decision depends on the value never having moved, rather than on its current contents, add a monotonic counter to the state you swap.