net: mention the cgo thread limit in package docs

Updates #63978

Change-Id: I39a5c812b4f604baf4ca5ffcff52b8dc17d4990d
GitHub-Last-Rev: 4ab6e262f4fd37ff32d6b3eb756fea187e5d6e53
GitHub-Pull-Request: golang/go#63990
Reviewed-on: https://go-review.googlesource.com/c/go/+/539361
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
Reviewed-by: Roland Shoemaker <roland@golang.org>

diff --git a/src/net/net.go b/src/net/net.go
index c434c96bf899afcb8f3c646f478520b70bf9a75f..387f2bb14dfe7dc2dc9adcb7edfa5a4c21b458f0 100644 (file)
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -46,8 +46,8 @@ It can use a pure Go resolver that sends DNS requests directly to the servers
 listed in /etc/resolv.conf, or it can use a cgo-based resolver that calls C
 library routines such as getaddrinfo and getnameinfo.
 
-By default the pure Go resolver is used, because a blocked DNS request consumes
-only a goroutine, while a blocked C call consumes an operating system thread.
+On Unix the pure Go resolver is preferred over the cgo resolver, because a blocked DNS
+request consumes only a goroutine, while a blocked C call consumes an operating system thread.
 When cgo is available, the cgo-based resolver is used instead under a variety of
 conditions: on systems that do not let programs make direct DNS requests (OS X),
 when the LOCALDOMAIN environment variable is present (even if empty),
@@ -57,6 +57,10 @@ when /etc/resolv.conf or /etc/nsswitch.conf specify the use of features that the
 Go resolver does not implement, and when the name being looked up ends in .local
 or is an mDNS name.
 
+On all systems (except Plan 9), when the cgo resolver is being used
+this package applies a concurrent cgo lookup limit to prevent the system
+from running out of system threads. Currently, it is limited to 500 concurrent lookups.
+
 The resolver decision can be overridden by setting the netdns value of the
 GODEBUG environment variable (see package runtime) to go or cgo, as in: