code review 5685060: net: more docs on deadlines

net: more docs on deadlines

Fixes issue 2777

[bradfitz, 2012-02-20 23:50:37]

Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://go.googlecode.com/hg/

[r, 2012-02-20 23:53:37]

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go
File src/pkg/net/net.go (right):

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode11
src/pkg/net/net.go:11: provided by the Dial, Listen, and Accept functions.
Conn and Listener should be documented here

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode79
src/pkg/net/net.go:79: // A deadline is an absolute point in time after which
I/O
s/point in /

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode84
src/pkg/net/net.go:84: // An idle timeout can be implemented by repeatedly
extending
i don't know what an idle timeout is.

[bradfitz, 2012-02-21 00:05:35]

Hello golang-dev@googlegroups.com, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[bradfitz, 2012-02-21 00:05:45]

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go
File src/pkg/net/net.go (right):

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode11
src/pkg/net/net.go:11: provided by the Dial, Listen, and Accept functions.
On 2012/02/20 23:53:37, r wrote:
> Conn and Listener should be documented here

Done. Suggestions welcome.

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode79
src/pkg/net/net.go:79: // A deadline is an absolute point in time after which
I/O
On 2012/02/20 23:53:37, r wrote:
> s/point in /

Done.

http://codereview.appspot.com/5685060/diff/2002/src/pkg/net/net.go#newcode84
src/pkg/net/net.go:84: // An idle timeout can be implemented by repeatedly
extending
On 2012/02/20 23:53:37, r wrote:
> i don't know what an idle timeout is.

The way Go's API used to be, and what a lot of people expect, is that you say:

SetTimeout(5 * time.Seconds)

... and then if any I/O operation doesn't respond in 5 seconds, you consider it
timed out.

That was problematic, and didn't work well with Read's semantics (it can return
a 1 byte at a time, each taking 5 seconds?).

But people still try to do things like that, reading from a Conn in a loop,
thinking they can just set the timeout once.

I'm trying to get across that you need to set the deadline before each call to
Read or Write if that's your goal.

Suggestions welcome.

[r, 2012-02-21 00:09:55]

LGTM
although i feel something is still missing, this is a big step

[bradfitz, 2012-02-21 00:11:27]

*** Submitted as http://code.google.com/p/go/source/detail?r=d2125f884ae5 ***

net: more docs on deadlines

Fixes issue 2777

R=golang-dev, r
CC=golang-dev
http://codereview.appspot.com/5685060