From babbf941c9287843807ea79820c33077b6b2a010 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 7 Mar 2012 14:55:09 -0500 Subject: [PATCH] net, net/rpc, reflect, time: document concurrency guarantees Fixes #1599. R=golang-dev, bradfitz CC=golang-dev https://golang.org/cl/5777043 --- src/pkg/net/net.go | 17 +++++++++++++---- src/pkg/net/rpc/client.go | 3 ++- src/pkg/reflect/value.go | 4 ++++ src/pkg/time/time.go | 3 ++- 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/src/pkg/net/net.go b/src/pkg/net/net.go index bf242ff8dd6..9ebcdbe996c 100644 --- 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 f7abf21f157..db2da8e4418 100644 --- 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 f3f7d639a0f..3974d02b717 100644 --- 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 "", 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 f7ded24d292..ee878389491 100644 --- 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.