New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
theclapp opened this Issue Oct 10, 2018 · 9 comments

Comments

Projects
None yet
5 participants
@theclapp
Contributor

theclapp commented Oct 10, 2018

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.

@ianlancetaylor ianlancetaylor changed the title from Clarify documentation on net.ListenConfig.Listen and related calls w.r.t. context to net: clarify documentation on net.ListenConfig.Listen and related calls w.r.t. context Oct 10, 2018

@ianlancetaylor ianlancetaylor added this to the Go1.12 milestone Oct 10, 2018

@mikioh

This comment has been minimized.

Contributor

mikioh commented Oct 11, 2018

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

This comment has been minimized.

Contributor

theclapp commented Oct 11, 2018

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

This comment has been minimized.

Contributor

mikioh commented Oct 12, 2018

@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

This comment has been minimized.

Contributor

theclapp commented Oct 15, 2018

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.

@BigMikes

This comment has been minimized.

Contributor

BigMikes commented Nov 1, 2018

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

This comment has been minimized.

Contributor

theclapp commented Nov 1, 2018

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

This comment has been minimized.

Contributor

mikioh commented Nov 2, 2018

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 #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

This comment has been minimized.

gopherbot commented Nov 4, 2018

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

@BigMikes

This comment has been minimized.

Contributor

BigMikes commented Nov 4, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment