Golang sync/atomic: comment for Uintptr.Or incorrectly describes return value

Go version

go version go1.25.1 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE=''
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/home/alex/.cache/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/home/alex/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build1035513965=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/home/alex/go/src/go/exp/1/go.mod'
GOMODCACHE='/home/alex/go/pkg/mod'
GOOS='linux'
GOPATH='/home/alex/go'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/home/alex/.config/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.25.1'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

I was reading the documentation for the sync/atomic package and noticed the comment for the (*Uintptr).Or method.

The actual behavior of the function is that it returns the previous value, not the updated one. This can be demonstrated with a simple program.

https://go.dev/play/p/yimvqhrwG3f

What did you see happen?

The source code comment for (*Uintptr).Or states that the method returns the "updated value".

// Or atomically performs a bitwise OR operation on x using the bitmask // provided as mask and returns the updated value after the OR operation.

https://github.com/golang/go/blob/master/src/sync/atomic/type.go#L235

What did you expect to see?

The comment should state that the method returns the previous value, before the OR operation was applied.

This would make it consistent with: The actual behavior of the function. The function's return variable name (old uintptr). The behavior of other similar methods like (*Uintptr).And.

A corrected comment, similar to the one for And, would be:

// Or atomically performs a bitwise OR operation on x using the bitmask // provided as mask and returns the the old value.

Comment From: prattmic

Thanks for the report. I've sent https://go.dev/cl/706816.

Comment From: gopherbot

Change https://go.dev/cl/706816 mentions this issue: sync/atomic: correct Uintptr.Or return doc

Comment From: prattmic

@gopherbot Please backport to 1.24 and 1.25. This is a documentation fix for sync/atomic.(*Uintptr).Or.

Comment From: gopherbot

Backport issue(s) opened: #75609 (for 1.24), #75610 (for 1.25).

Remember to create the cherry-pick CL(s) as soon as the patch is submitted to master, according to https://go.dev/wiki/MinorReleases.

Comment From: gopherbot

Change https://go.dev/cl/706855 mentions this issue: [release-branch.go1.24] sync/atomic: correct Uintptr.Or return doc

Comment From: gabyhelp

Related Code Changes

• sync/atomic: correct Uintptr.Or return doc

Related Documentation

• Package atomic > type Uintptr 1.19 > func (*Uintptr) Or 1.23

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

Comment From: gopherbot

Change https://go.dev/cl/706856 mentions this issue: [release-branch.go1.25] sync/atomic: correct Uintptr.Or return doc