diff options
Diffstat (limited to 'libgo/go/net/net.go')
| -rw-r--r-- | libgo/go/net/net.go | 73 |
1 files changed, 61 insertions, 12 deletions
diff --git a/libgo/go/net/net.go b/libgo/go/net/net.go index 79d36a2a813..9ebcdbe996c 100644 --- a/libgo/go/net/net.go +++ b/libgo/go/net/net.go @@ -2,8 +2,41 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -// Package net provides a portable interface to Unix networks sockets, -// including TCP/IP, UDP, domain name resolution, and Unix domain sockets. +/* +Package net provides a portable interface for network I/O, including +TCP/IP, UDP, domain name resolution, and Unix domain sockets. + +Although the package provides access to low-level networking +primitives, most clients will need only the basic interface provided +by the Dial, Listen, and Accept functions and the associated +Conn and Listener interfaces. The crypto/tls package uses +the same interfaces and similar Dial and Listen functions. + +The Dial function connects to a server: + + conn, err := net.Dial("tcp", "google.com:80") + if err != nil { + // handle error + } + fmt.Fprintf(conn, "GET / HTTP/1.0\r\n\r\n") + status, err := bufio.NewReader(conn).ReadString('\n') + // ... + +The Listen function creates servers: + + ln, err := net.Listen("tcp", ":8080") + if err != nil { + // handle error + } + for { + conn, err := ln.Accept() + if err != nil { + // handle error + continue + } + go handleConnection(conn) + } +*/ package net // TODO(rsc): @@ -21,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 @@ -33,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. @@ -42,21 +78,28 @@ type Conn interface { RemoteAddr() Addr // SetDeadline sets the read and write deadlines associated - // with the connection. + // with the connection. It is equivalent to calling both + // SetReadDeadline and SetWriteDeadline. + // + // A deadline is an absolute time after which I/O operations + // fail with a timeout (see type Error) instead of + // blocking. The deadline applies to all future I/O, not just + // the immediately following call to Read or Write. + // + // An idle timeout can be implemented by repeatedly extending + // the deadline after successful Read or Write calls. + // + // A zero value for t means I/O operations will not time out. SetDeadline(t time.Time) error - // SetReadDeadline sets the deadline for all Read calls to return. - // If the deadline is reached, Read will fail with a timeout - // (see type Error) instead of blocking. + // 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 all Write calls to return. - // 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. + // 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. SetWriteDeadline(t time.Time) error } @@ -68,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 @@ -86,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. @@ -95,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. @@ -111,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. |