Document `Subscription` (and possibly other types) as thread-safe

[mprimi]

Proposed change

Subscription (and probably) other types, are thread safe.
This is great, it simplifies multi-threaded application code which does not need to provide its own locking.

e.g.

// pseudo-go
for i in numThreads {
  go func() {
    msgs, error :=  sub.Fetch
    [... handle error...]
    for msg in msgs {
      [... process msgs ...]
      [... ack msg ...]
    }
  }
}

This Just Works! Which is fantastic.

However, the cautious programmer does not know!
Without any explicit indication, they should assume that sub is NOT thread safe.
Therefore they will need to create one sub per thread OR introduce an additional lock around a shared sub, both of which are superfluous and less efficient.

From the Go comment guidelines:

By default, programmers should expect that a type is safe for use only by a single goroutine at a time. If a type provides stronger guarantees, the doc comment should state them

And later:

using an instance of a type in any way, including calling a method, is typically assumed to be restricted to a single goroutine at a time. If the methods that are safe for concurrent use are not documented in the type’s doc comment, they should be documented in per-method comments

Proposed change:

• Flag all thread-safe methods as such, so developers can take advantage of this property

Use case

See above

Contribution

No response

[mprimi]

Thank you @alexbozhenko for finding the references in the doc spec.