Navigation Menu

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

Jump to bottom

net: (*ListenConfig).Listen Context behavior is undocumented #50861

Open
bcmills opened this issue Jan 27, 2022 · 3 comments
Open

net: (*ListenConfig).Listen Context behavior is undocumented #50861

bcmills opened this issue Jan 27, 2022 · 3 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@bcmills
Copy link
Contributor

bcmills commented Jan 27, 2022

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

go1.17.6

Does this issue reproduce with the latest release?

Yes.

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

N/A

What did you do?

View the documentation for the (*net.ListenConfig).Listen method.

What did you expect to see?

The method has this signature:

func (lc *ListenConfig) Listen(ctx context.Context, network, address string) (Listener, error)

I expected to see a description of what happens when the ctx parameter is done, to help get some insight into #46520.

Is ctx used at all after Listen returns? It a typical API it would not be, but this appears to be retrofitting a Context into the existing net.Listener interface in some fashion, so I don't really know. (I tried reading the source code, but the ctx parameter is passed through an awful lot of helper-functions and network-abstraction interfaces.)

What did you see instead?

No mention whatsoever of the ctx parameter or its semantics:

Listen announces on the local network address.

See func Listen for a description of the network and address parameters.

This API was added in CL 72810 (Go 1.11) for #9661.
(CC @ianlancetaylor @bradfitz @AudriusButkevicius)
@bcmills bcmills added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 27, 2022
@bcmills bcmills added this to the Backlog milestone Jan 27, 2022
@ianlancetaylor
Copy link
Contributor

The context argument is not used for anything after Listen returns. It's there to permit an early return for a DNS lookup, and because functions like internetSocket take a context argument even though it won't be used for the particular case of Listen.

@ianlancetaylor
Copy link
Contributor

I note that DialContext also does not document how the context argument is used (it also does not use the context for anything after DialContext returns).

@Reasno
Copy link

Reasno commented Jan 28, 2022

I'd welcome the documentation of context. Personally, I dislike the fact that the go ecosystem at large tends to throw in a context without clear documentation on how the context will be used. Sometimes this creates ambiguity briefly touched in this blog post: https://go.dev/blog/context-and-structs

@weiiwang01 weiiwang01 mentioned this issue Mar 21, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
4 participants
@ianlancetaylor @Reasno @bcmills @gopherbot