doc comment for io.Closer

[Dan Kortschak]

I just noticed today that the io.Closer docs say that "The behavior of
Close after the first call is undefined. Specific implementations may
document their own behavior".

Should this be "unspecified" rather than "undefined"?

Dan

[Ian Lance Taylor]

The general concern here is that if there is something like a file
descriptor involved, and if the Close method doesn't take special
protection to avoid problems with multiple calls to Close, then a
first call to Close may close the descriptor, then some other
goroutine may open something and get the same descriptor number, and
then a second call to Close may close the same descriptor number,
breaking the other goroutine unexpectedly. Historically, we forgot to
say that it was OK to call Close multiple times. By the time we wrote
that comment, there were many existing Close implementations out
there, and it wasn't clear that we wanted to, or reasonably could,
make them non-compliant. So unfortunately I think we kind of do mean
"undefined".

Ian

[Dan Kortschak]

On Thu, 2021-07-29 at 11:45 -0700, Ian Lance Taylor wrote:
> > Should this be "unspecified" rather than "undefined"?
>
> The general concern here is that if there is something like a file
> descriptor involved, and if the Close method doesn't take special
> protection to avoid problems with multiple calls to Close, then a
> first call to Close may close the descriptor, then some other
> goroutine may open something and get the same descriptor number, and
> then a second call to Close may close the same descriptor number,
> breaking the other goroutine unexpectedly. Historically, we forgot
> to
> say that it was OK to call Close multiple times. By the time we
> wrote
> that comment, there were many existing Close implementations out
> there, and it wasn't clear that we wanted to, or reasonably could,
> make them non-compliant. So unfortunately I think we kind of do mean
> "undefined".

Yeah, fair enough. The leakage to other goroutines definitely justifies
the undefined wording.

Dan