net: document Dial thread safety, timeout example

[kevinburke1]

I'm trying to figure out whether port 80 on the IP address 169.254.169.254 is reachable from the host I'm on. Essentially all I want to do is connect to it with a short timeout. I'm a little confused by the net package on this point.

• Generally speaking I thought timeouts were deprecated in favor of using a context with a timeout parameter. However, the net package still has a DialTimeout top level function and no DialContext.
• There is a (*Dialer) DialContext() method. After some reading I see that the empty Dialer is equivalent to calling net.Dial, there's no DefaultDialer or similar. However, is a Dialer safe to use concurrently? (eg. If I am going to use DialContext, can I just have one package-level Dialer or similar, instead of allocating a new one each time.) It's not clear from the documentation.

It might be good to have some examples here, some guidance about when to use Context vs. Timeout, and a short note about whether a Dialer is safe for concurrent use.

[bcmills]

CC @mikioh @ianlancetaylor

[ianlancetaylor]

It's safe to call Dialer methods concurrently. It's of course not safe to change Dialer fields concurrently or concurrently with method calls. I agree that this should be documented.

[tomocy]

Can I tackle on this??

_{Sent with GitHawk}

[ianlancetaylor]

@tomocy Sure. Thanks.

[gopherbot]

Change https://golang.org/cl/191879 mentions this issue: net: add example of Dialer