code review 162680043: os: document that users of Fd should keep f alive

os: document that users of Fd should keep f alive

Fixes issue 9046.

[rsc, 2014-11-04 15:17:03]

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

I'd like you to review this change to
https://code.google.com/p/go/

[r, 2014-11-04 17:39:39]

https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go
File src/os/file_plan9.go (right):

https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go#newc...
src/os/file_plan9.go:31: // being used, call f.Close explicitly when finished
with both f and
the 'when' (as opposed to 'only when') weakens the message and the 'explicitly'
confuses. how else can i call it?

// To avoid f from being garbage collected while the file descriptor is
// still active, do not call f.Close until finished with both f and the
// file descriptor.

[rsc, 2014-11-04 17:59:22]

On 2014/11/04 17:39:39, r wrote:
> https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go
> File src/os/file_plan9.go (right):
> 
>
https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go#newc...
> src/os/file_plan9.go:31: // being used, call f.Close explicitly when finished
> with both f and
> the 'when' (as opposed to 'only when') weakens the message and the
'explicitly'
> confuses. how else can i call it?
> 
> // To avoid f from being garbage collected while the file descriptor is
> // still active, do not call f.Close until finished with both f and the
> // file descriptor.

That's sort of the opposite of what I'm trying to say. 
The problem is that people drop f on the floor, letting the garbage collector do
the f.Close implicitly.
That is, people write:

f, _ := os.Open(file)
fd := f.Fd()
// no more use of f
// code uses fd, f eventually garbage collected and closed by finalizer, fd
stops working

I am trying to say that code must keep f alive while using fd, and the best way
to do that is to place a call to f.Close after the code is done with fd. That
keeps f alive *and* makes sure the Close happens when you expect, not earlier,
not later.

f, _ := os.Open(file)
fd := f.Fd()
// code uses fd
f.Close()

Better text welcome.

[r, 2014-11-04 19:24:19]

https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go
File src/os/file_plan9.go (right):

https://codereview.appspot.com/162680043/diff/40001/src/os/file_plan9.go#newc...
src/os/file_plan9.go:31: // being used, call f.Close explicitly when finished
with both f and
how about we just keep it simple and drop the last sentence, which i find
confusing (and clearly didn't understand the purpose of before).

// Fd returns the integer Plan 9 file descriptor referencing the open file.
// The file descriptor remains valid only until f.Close is called or f is
garbage collected.

[rsc, 2014-11-06 04:03:33]

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

Please take another look.

[r, 2014-11-06 04:22:50]

LGTM after transpose in all three

https://codereview.appspot.com/162680043/diff/60001/src/os/file_plan9.go
File src/os/file_plan9.go (right):

https://codereview.appspot.com/162680043/diff/60001/src/os/file_plan9.go#newc...
src/os/file_plan9.go:29: // The file descriptor is only valid until f.Close is
called or f is garbage collected.
s/only valid/valid only/
 (different meaning; english is tricky)

[rsc, 2014-11-06 14:36:56]

*** Submitted as https://code.google.com/p/go/source/detail?r=1e082c42fb76 ***

os: document that users of Fd should keep f alive

Fixes issue 9046.

LGTM=r
R=r
CC=golang-codereviews
https://codereview.appspot.com/162680043