Skip to content
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
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@theclapp
Copy link
Contributor

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 Clarify documentation on net.ListenConfig.Listen and related calls w.r.t. context net: clarify documentation on net.ListenConfig.Listen and related calls w.r.t. context Oct 10, 2018
@ianlancetaylor ianlancetaylor added help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Oct 10, 2018
@ianlancetaylor ianlancetaylor added this to the Go1.12 milestone Oct 10, 2018
@mikioh
Copy link
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
Copy link
Contributor Author

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
Copy link
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
Copy link
Contributor Author

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
Copy link
Contributor

gmichelo 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
Copy link
Contributor Author

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
Copy link
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:

@gopherbot
Copy link

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

@gmichelo
Copy link
Contributor

gmichelo 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.

@andybons andybons modified the milestones: Go1.12, Go1.13 Feb 12, 2019
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
boreq added a commit to planetary-social/scuttlego that referenced this issue Jan 10, 2023
This is not documented but closing the context passed to Listen doesn't close the listener.

See golang/go#28120.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

7 participants