"Thread-safe" adjective for use in Golang documentation

“Thread-safe”, “thread-safety” are standard computer science terms. “Thread-safe” is commonly used as an adjective or an adverb in the documentation comments for classes and methods in Java.

In the documentation for types and methods in Go, it feels unnatural to use this term because there are no “threads” in the Go execution model. “Goroutine-safe” feels contrived. “FooBar is not safe for use [calling] from concurrent goroutines” is very mouthful.

What is the preferred way to describe the concurrency guarantees (or the lack thereof) of a Go type or a method in the doc?

safe for concurrent use

Unless explicitly stated that it is safe for concurrent use, it is unsafe for concurrent use.

Package rand

The default Source is safe for concurrent use by multiple goroutines, but Sources created by NewSource are not.

Seed, unlike the Rand.Seed method, is safe for concurrent use.

Read, unlike the Rand.Read method, is safe for concurrent use.

Unlike the default Source used by top-level functions, this source is not safe for concurrent use by multiple goroutines.

1 Like

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.