net: clarify documentation on net.ListenConfig.Listen and related calls w.r.t. context

[theclapp]

What version of Go are you using (go version)?

go version go1.11.1 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOOS="linux"

What did you do?

I created a net.ListenConfig.Listen(cancelableCtx, "unix", "/path/to/socket") to create a Unix socket, and called Accept on said listener.

What did you expect to see?

I expected canceling the context to cancel the Accept.

What did you see instead?

The Accept was not canceled.

---

So maybe my expectation was wrong. I reasoned "Why else would there be a context there if not to cancel (or time out) the Accept calls?". But clearly not.

I asked on the #general channel in the Gophers Slack and was reminded that Dial, for example, specifically says that once Dial completes, the context it's given doesn't affect the connection, and that probably Listen & Accept were similar. That does appear to be the case.

So, for folks like me that are not terribly familiar with network or socket programming, would it be possible to note in the Listen & Accept docs that the given context doesn't affect the later Accept? And maybe even what the Listen context actually does; it wasn't 100% clear to me.

Thanks.

[mikioh]

The method Accept of {TCP,Unix}Listener is part of a connection setup for passive-open connections. It might be better to have AcceptContext(context.Context) (Conn, error) for shooting the root cause of confusion.

[theclapp]

Note that no other Accept or Accept{TCP|Unix} functions currently take a context, so if you/we implemented @mikioh's suggestion, we'd probably want to add several others. Adding it to the net.Listen interface would break the Go 1 compatibility contract though, yes?

In any case, it's easy enough to implement yourself, so it might not be worth it:

go func() {
	<-ctx.Done()
	listener.Close()
}()

[mikioh]

@theclapp,

I think the clarification probably needs to address #10527 partially. Apart from #10527, adding a method to the existing sturct types doesn't mean the violation of Go 1 promise, also doesn't mean changing the existing interfaces such as net.Listener.

[theclapp]

adding a method to the existing struct types doesn't mean the violation of Go 1 promise

Agree.

also doesn't mean changing the existing interfaces such as net.Listener

I agree, it doesn't necessarily mean that. But not doing it would leave a (to me) odd inconsistency between {TCP|Unix}Accept and the net.Listen interface, where the first two would have AcceptContext but the latter wouldn't. But I'll certainly leave it to wiser heads than mine to weigh the importance of these issues.

[gmichelo]

The context passed to a given function should affect only that function, shouldn't it? I am not sure about this, but do we have other cases in Go where a context is kind of "shared" from one method call to another?

Anyhow, I believe that clarify is always a good thing. If we agree on this, I can take care of it.

Regarding adding a new AcceptContext(), I would keep the interface as simple as possible. Accept() is clearly a blocking call and the caller must deal with it. Therefore, I think it would be neater to leave the API as it is.

[theclapp]

Sure, what I'm really asking for is a documentation update. Adding AcceptContext() seems like overkill, especially given that you can roll your own cancellation in four lines (posted earlier).

[mikioh]

If we agree on this, I can take care of it.

Thanks. The deliverable (changelist) should contain the consensus like the following:

• whether we use a context.Context parameter for ListenConfig.Listen{,Packet} to fix net: concurrent Accept-Close with no timeout on TCPListener defers closing underlying socket #10527,
• if not, just document that the context.Context parameter doesn't interfere with the returned connection, not only for Listen but Dial for package-level consistency,
• and add a test case that guarantees the behavior.

[gopherbot]

Change https://golang.org/cl/147378 mentions this issue: net: update documentation for Listen and ListenPacket

[gmichelo]

I updated the documentation, added the check for nil context and more test cases for scenario mentioned above.

Please give it a look when you can, thanks a lot.