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

[bcmills]

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)

[ianlancetaylor]

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]

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]

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

[mndrix]

Looks like this was fixed at some point. As of go1.24rc1, ListenConfig.Listen docs say:

The ctx argument is used while resolving the address on which to listen;
it does not affect the returned Listener.

[ianlancetaylor]

Thanks, closing.