singleflight in Go: Collapsing... Note

singleflight in Go: Collapsing Duplicate Work Under Load

A cache stampede occurs when a cache expires and many requests simultaneously miss, leading to duplicated expensive operations. Go's golang.org/x/sync/singleflight package addresses this by ensuring only one execution of a function runs for a given key. Concurrent callers with the same key will wait and receive the result from that single execution. The Do method takes a key and a function, executing the function only for the first caller. Subsequent callers block until the function completes and then share its result. A shared boolean indicates if the result was distributed to multiple callers, useful for metrics.Singleflight is not a cache itself; it collapses calls only when they overlap in time. The typical pattern involves checking a cache, then using group.Do on a miss, and finally writing the result back to the cache. A critical caveat is that the returned value is shared, so mutable types like pointers, slices, and maps can lead to data races if modified by multiple goroutines. To avoid this, treat returned values as immutable or return copies that callers can own and modify independently.For non-blocking behavior, DoChan returns a channel, allowing callers to respond to context cancellation. However, the function runs under the context of the first caller, so detaching work from request-specific contexts is advised for shared operations. The Forget method can be used to clear a key, allowing subsequent calls to start new executions, which is useful for capping the blast radius of failing operations. Singleflight belongs at the boundary where duplicate work is expensive, such as cache loading or slow upstream calls, not within domain logic. The two main pitfalls are the shared value and the context of the first caller.
CdXz5zHNQW_EMU9QnIza4.webp