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 bf242ff8dd65419a8713201890484ee0ec3aa2c0..9ebcdbe996cde22c7c4bdd0261619ded64af703a 100644 (file)
--- a/src/pkg/net/net.go
+++ b/src/pkg/net/net.go
@@ -54,6 +54,8 @@ type Addr interface {
 }
 
 // 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 @@ type Conn interface {
        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 @@ type Conn interface {
        // 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 @@ type Error interface {
 }
 
 // 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 @@ type PacketConn interface {
        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 @@ type PacketConn interface {
        // 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 @@ type PacketConn interface {
 }
 
 // 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 f7abf21f157f9089211ee92922a614e53b24b0a6..db2da8e4418d32ba2c6200d1e263eebe0206068a 100644 (file)
--- a/src/pkg/net/rpc/client.go
+++ b/src/pkg/net/rpc/client.go
@@ -36,7 +36,8 @@ type Call struct {
 
 // 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 f3f7d639a0f05c9dd691b31ef7bebe743b78d97d..3974d02b717f11521bbbce2c4ef0c35e82bc1498 100644 (file)
--- a/src/pkg/reflect/value.go
+++ b/src/pkg/reflect/value.go
@@ -54,6 +54,10 @@ func memmove(adst, asrc unsafe.Pointer, n uintptr) {
 // 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 f7ded24d2929d42599f2f30170c7c78bad93f875..ee8783894915802e77786e9c10061029ab802c8b 100644 (file)
--- a/src/pkg/time/time.go
+++ b/src/pkg/time/time.go
@@ -13,7 +13,8 @@ import "errors"
 //
 // 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.