net: document concurrency safety and example for Dialer

Fixes #33743.

Change-Id: I80621321d56b6cf312a86e272800f1ad03c5544c
GitHub-Last-Rev: d91cb3697516ccfc3f956e97837404cbfee5922f
GitHub-Pull-Request: golang/go#33856
Reviewed-on: https://go-review.googlesource.com/c/go/+/191879
Run-TryBot: Emmanuel Odeke <emm.odeke@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>

diff --git a/src/net/dial.go b/src/net/dial.go
index 4d55a95ddf6b9b6359b5544cad5af842dd88b213..60ab0f2973cc9e69c1abd7d352aa8f489d678aa6 100644 (file)
--- a/src/net/dial.go
+++ b/src/net/dial.go
@@ -23,6 +23,8 @@ const (
 // The zero value for each field is equivalent to dialing
 // without that option. Dialing with the zero value of Dialer
 // is therefore equivalent to just calling the Dial function.
+//
+// It is safe to call Dialer's methods concurrently.
 type Dialer struct {
        // Timeout is the maximum amount of time a dial will wait for
        // a connect to complete. If Deadline is also set, it may fail

diff --git a/src/net/example_test.go b/src/net/example_test.go
index e4d732e68a16f326a31082b475ab5ada5ed3b700..ef8c38f9f4ab6696b9d834ab98116ea3805800ff 100644 (file)
--- a/src/net/example_test.go
+++ b/src/net/example_test.go
@@ -5,10 +5,12 @@
 package net_test
 
 import (
+       "context"
        "fmt"
        "io"
        "log"
        "net"
+       "time"
 )
 
 func ExampleListener() {
@@ -37,6 +39,22 @@ func ExampleListener() {
        }
 }
 
+func ExampleDialer() {
+       var d net.Dialer
+       ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+       defer cancel()
+
+       conn, err := d.DialContext(ctx, "tcp", "localhost:12345")
+       if err != nil {
+               log.Fatalf("Failed to dial: %v", err)
+       }
+       defer conn.Close()
+
+       if _, err := conn.Write([]byte("Hello, World!")); err != nil {
+               log.Fatal(err)
+       }
+}
+
 func ExampleIPv4() {
        fmt.Println(net.IPv4(8, 8, 8, 8))