net: clarify net.Conn concurrency requirement

[FiloSottile]

From the net.Conn docs:

Multiple goroutines may invoke methods on a Conn simultaneously.

I'm not sure if this should be interpreted as different methods can be called concurrently, or as the same method can be called concurrently.

I suspect, judging from x/net/nettest's ConcurrentMethods and from most implementations, that it's the former. If so, should we change the docs to include "may invoke distinct methods"?

[ianlancetaylor]

It's the former: any methods may be called concurrently. But changing the docs to say distinct methods would suggest that you could not call the same method concurrently--e.g., two concurrent calls to Write.

Personally I think the current text is clear but I'm open to counter arguments.

[FiloSottile]

Calling the same method concurrently however is not part of the interface contract. Implementations might allow it, but don't have to. With the current text, it's not clear to me if a net.Conn implementation that breaks for concurrent calls to Read is correct.

[ianlancetaylor]

I don't understand. The text is, as you say, "Multiple goroutines may invoke methods on a Conn simultaneously." To me that clearly states that multiple goroutines may invoke the Read method simultaneously. Are you saying that that does not work?

[FiloSottile]

Ah, I interpreted your first message the other way around.

That seems more strict than what I've seen implemented in practice, but I'm willing to believe it.

x/net/nettest's ConcurrentMethods should test for it then, though, because it looks like it only tests concurrent calls of distinct methods.

[bradfitz]

Also, some implementations may promise more: e.g. UDPConn permitting concurrent Write calls.

[networkimprov]

Doesn't TCPConn allow simultaneous Write() to a single net.Conn? The docs certainly imply that.

I make TCPConn.Write calls from one goroutine while another does io.Copy (invoking sendfile()), and haven't seen any errors that indicated "connection in use".

Pls do test this formally if possible :-)

@gopherbot add Testing

[FiloSottile]

@bradfitz I'm confused again, AFAICT @ianlancetaylor is saying that all net.Conn implementations must permit concurrent Write calls, so it wouldn't be promising more.

I'll argue that we should make the docs more explicit after all.

[bercknash]

As a C programmer new to go, I also find the statement "Multiple goroutines may invoke methods on a Conn simultaneously" to be a bit ambiguous. It makes sense that it's probably safe to simultaneously call Read() and Write() from separate goroutines, but it's less clear what's going to happen if, say, I call conn.Write() from several goroutines simultaneously. I take the statement to mean that I "may" do it, but if I do, does my data get randomly interleaved? Or is it truly threadsafe and simultaneous conn.Write() commands will block while the others are writing?

[networkimprov]

@FiloSottile you removed the Testing label. Does that mean tests have been added for concurrent calls of the same methods?

If not, we should create an issue to request that...

[FiloSottile]

Ah, my bad, I didn't get why it was tagged Testing. I still don't have clear what the interface contract is, so it feels like first we need to update the docs, and then the tests.

[ianlancetaylor]

@bercknash A single Write call will acquire a write lock on the net.Conn until the Write is complete or has an error. So concurrent Write calls are permitted and will not interleave.

[bercknash]

@bercknash A single Write call will acquire a write lock on the net.Conn until the Write is complete or has an error. So concurrent Write calls are permitted and will not interleave.

Thanks for clarifying. I gathered as much from digging through the code, but it's the sort of thing I think the docs should make explicitly clear without having to dive in.