net, net/rpc, reflect, time: document concurrency guarantees
Fixes #1599.
R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/5777043
diff --git a/src/pkg/net/net.go b/src/pkg/net/net.go
index bf242ff..9ebcdbe 100644
--- a/src/pkg/net/net.go
+++ b/src/pkg/net/net.go
@@ -54,6 +54,8 @@
}
// Conn is a generic stream-oriented network connection.
+//
+// Multiple goroutines may invoke methods on a Conn simultaneously.
type Conn interface {
// Read reads data from the connection.
// Read can be made to time out and return a Error with Timeout() == true
@@ -66,6 +68,7 @@
Write(b []byte) (n int, err error)
// Close closes the connection.
+ // Any blocked Read or Write operations will be unblocked and return errors.
Close() error
// LocalAddr returns the local network address.
@@ -89,11 +92,11 @@
// A zero value for t means I/O operations will not time out.
SetDeadline(t time.Time) error
- // SetReadDeadline sets the deadline for Read calls.
+ // SetReadDeadline sets the deadline for future Read calls.
// A zero value for t means Read will not time out.
SetReadDeadline(t time.Time) error
- // SetWriteDeadline sets the deadline for Write calls.
+ // SetWriteDeadline sets the deadline for future Write calls.
// Even if write times out, it may return n > 0, indicating that
// some of the data was successfully written.
// A zero value for t means Write will not time out.
@@ -108,6 +111,8 @@
}
// PacketConn is a generic packet-oriented network connection.
+//
+// Multiple goroutines may invoke methods on a PacketConn simultaneously.
type PacketConn interface {
// ReadFrom reads a packet from the connection,
// copying the payload into b. It returns the number of
@@ -126,6 +131,7 @@
WriteTo(b []byte, addr Addr) (n int, err error)
// Close closes the connection.
+ // Any blocked ReadFrom or WriteTo operations will be unblocked and return errors.
Close() error
// LocalAddr returns the local network address.
@@ -135,13 +141,13 @@
// with the connection.
SetDeadline(t time.Time) error
- // SetReadDeadline sets the deadline for all Read calls to return.
+ // SetReadDeadline sets the deadline for future Read calls.
// If the deadline is reached, Read will fail with a timeout
// (see type Error) instead of blocking.
// A zero value for t means Read will not time out.
SetReadDeadline(t time.Time) error
- // SetWriteDeadline sets the deadline for all Write calls to return.
+ // SetWriteDeadline sets the deadline for future Write calls.
// If the deadline is reached, Write will fail with a timeout
// (see type Error) instead of blocking.
// A zero value for t means Write will not time out.
@@ -151,11 +157,14 @@
}
// A Listener is a generic network listener for stream-oriented protocols.
+//
+// Multiple goroutines may invoke methods on a Listener simultaneously.
type Listener interface {
// Accept waits for and returns the next connection to the listener.
Accept() (c Conn, err error)
// Close closes the listener.
+ // Any blocked Accept operations will be unblocked and return errors.
Close() error
// Addr returns the listener's network address.
diff --git a/src/pkg/net/rpc/client.go b/src/pkg/net/rpc/client.go
index f7abf21..db2da8e 100644
--- a/src/pkg/net/rpc/client.go
+++ b/src/pkg/net/rpc/client.go
@@ -36,7 +36,8 @@
// Client represents an RPC Client.
// There may be multiple outstanding Calls associated
-// with a single Client.
+// with a single Client, and a Client may be used by
+// multiple goroutines simultaneously.
type Client struct {
mutex sync.Mutex // protects pending, seq, request
sending sync.Mutex
diff --git a/src/pkg/reflect/value.go b/src/pkg/reflect/value.go
index f3f7d63..3974d02 100644
--- a/src/pkg/reflect/value.go
+++ b/src/pkg/reflect/value.go
@@ -54,6 +54,10 @@
// its String method returns "<invalid Value>", and all other methods panic.
// Most functions and methods never return an invalid value.
// If one does, its documentation states the conditions explicitly.
+//
+// A Value can be used concurrently by multiple goroutines provided that
+// the underlying Go value can be used concurrently for the equivalent
+// direct operations.
type Value struct {
// typ holds the type of the value represented by a Value.
typ *commonType
diff --git a/src/pkg/time/time.go b/src/pkg/time/time.go
index f7ded24..ee87838 100644
--- a/src/pkg/time/time.go
+++ b/src/pkg/time/time.go
@@ -13,7 +13,8 @@
//
// Programs using times should typically store and pass them as values,
// not pointers. That is, time variables and struct fields should be of
-// type time.Time, not *time.Time.
+// type time.Time, not *time.Time. A Time value can be used by
+// multiple goroutines simultaneously.
//
// Time instants can be compared using the Before, After, and Equal methods.
// The Sub method subtracts two instants, producing a Duration.
