document concurrency properties

[bradfitz]

We should document what methods are safe to call concurrently.

In general things aren't safe (and that's the default to assume in Go when not documented otherwise), but we have plenty of stuff that is safe to call concurrently. Anything on a value type, for instance. And the func returned by IPSet.ContainsFunc.

But also IPPrefix.Contains and IPRange.Contains and IPPrefix.Overlaps and IPRange.Overlaps. But not IPSet.Overlaps if #109 goes in.

So maybe we should decide what rules we want before we decide to submit #109.

/cc @danderson @josharian @mdlayher

[josharian]

I'd love to be able to say that everything in the package is concurrency-safe. It makes it really, really nice to use, particularly for low-level types.

If that bar is unreasonable to clear, I'd vote to split that package into concurrency-safe types (probably the simplest, lowest-level types like IP, IPPrefix, IPPort) and non-concurrency-safe types, and make no guarantees whatsoever about the latter ones.

[josharian]

I'd like to come to a decision here. The menu of options seems to be:

1. Declare that value types (IP, IPRange, IPPrefix) are concurrency safe. Reference types (IPSet) are not.
2. Declare that all types are concurrency safe. Add a mutex to IPSet.
3. Declare that no types are concurrency safe.

My 2c:

3 seems like the worst option.

Given that we can backwards-compatibly go from 1 to 2, 1 seems the lower-risk option of the two. Mutex are cheap, though, so I'm also OK with 2.

[danderson]

I was assuming 1 as our default. Concurrency safety is fantastic for consumers, so we should strive for it.

I'm on the fence about 2, but as long as we don't have any callback-based functions, I think throwing a mutex on it and guaranteeing that all types are concurrency-safe LGTM.

Agree on 3, let's not do that.