Skip to content

unique: document thread safety #69637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
Deleplace opened this issue Sep 26, 2024 · 5 comments
Closed

unique: document thread safety #69637

Deleplace opened this issue Sep 26, 2024 · 5 comments
Assignees
@mknyszek
Labels
Documentation Issues describing a change to documentation. NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.24

Comments

@Deleplace
Copy link
Contributor

Go version

go version go1.23.1 darwin/arm64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='arm64'
GOBIN=''
GOCACHE='/Users/deleplace/Library/Caches/go-build'
GOENV='/Users/deleplace/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMODCACHE='/Users/deleplace/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/deleplace/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.23.1'
GODEBUG=''
GOTELEMETRY='on'
GOTELEMETRYDIR='/Users/deleplace/Library/Application Support/go/telemetry'
GCCGO='gccgo'
GOARM64='v8.0'
AR='ar'
CC='clang'
CXX='clang++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/p4/g7fnpss96g5708_mmv3cxzgh0000gn/T/go-build1180605141=/tmp/go-build -gno-record-gcc-switches -fno-common'

What did you do?

Read https://pkg.go.dev/unique

What did you see happen?

No mention of concurrency or safety

What did you expect to see?

A sentence "unique.Make is safe for concurrent use by multiple goroutines."

Discussion

The general rule in Go documentation is that when something is not documented as thread-safe, then it should be regarded as not thread-safe.

However, the unique package is in fact thread-safe, and this undocumented fact is not obvious to some users.

I suggest to follow the example of:

  • rand: "Top-level functions, such as Float64 and Int, are safe for concurrent use by multiple goroutines."
  • sync.Pool: "A Pool is safe for use by multiple goroutines simultaneously."
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Sep 26, 2024
@ianlancetaylor
Copy link
Member

CC @mknyszek

@mknyszek mknyszek self-assigned this Sep 26, 2024
@mknyszek mknyszek added the NeedsFix The path to resolution is known, but the work has not been done. label Sep 26, 2024
@mknyszek mknyszek added this to the Go1.24 milestone Sep 26, 2024
@mknyszek
Copy link
Contributor

Thanks. I'll send a CL out today.

@Deleplace
Copy link
Contributor Author

Less importantly, we may also say "unique.Handle.Value is safe for concurrent use by multiple goroutines."

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/616235 mentions this issue: unique: clarify concurrent use of Make and Handle.Value

@magical
Copy link
Contributor

magical commented Oct 1, 2024

Note that, according to https://go.dev/doc/comment,

programmers can assume that a top-level function is safe to call from multiple goroutines; this fact need not be stated explicitly.

So unique.Make needn't call out its thread safety. (It probably doesn't hurt though.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@mknyszek mknyszek

Labels
Documentation Issues describing a change to documentation. NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.24
Development

No branches or pull requests
5 participants
@magical @mknyszek @ianlancetaylor @gopherbot @Deleplace