os: document File's concurrent operation resource limits

Document that *os.File is subject to resource limits
for concurrent operations. We aren't documenting
a specific number of concurrent operations because that
number is OS/system dependent. This limit comes from:
    internal/poll/fd_mutex.go
where we use 20 bits to count locks.

Fixes #32544

Change-Id: I7d305d4aaba5b2dbc6f1ab8c447117fde5e31a66
Reviewed-on: https://go-review.googlesource.com/c/go/+/181841
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/os/file.go b/src/os/file.go
index 96df3fb5e90fb24a3db90659fb3d585f29834a5a..c13babe5f7fad8ee418dc1783fc8e7e7413aea4e 100644 (file)
--- a/src/os/file.go
+++ b/src/os/file.go
@@ -34,6 +34,10 @@
 //     }
 //     fmt.Printf("read %d bytes: %q\n", count, data[:count])
 //
+// Note: The maximum number of concurrent operations on a File may be limited by
+// the OS or the system. The number should be high, but exceeding it may degrade
+// performance or cause other issues.
+//
 package os
 
 import (