TcpStream::close_read has platform-dependent semantics

[jbapple]

Under the hood, TcpStream::close_read calls libc::shutdown(self.fd(), libc::SHUT_RD). According to http://stackoverflow.com/questions/14740852/linux-socket-close-vs-shutdown/14743440#14743440 ,

Unix will ACK it and throw it away; Linux will ACK it and buffer it, which will eventually stall the sender; Windows will issue an RST, which the sender sees as 'connection reset by peer'.

Should there be a note in the comment on close_read that the behavior is platform-dependent?

[steveklabnik]

/cc rust-lang/rfcs#807 and @alexcrichton

[alexcrichton]

Now that the function is named shutdown and will be clearly documented as calling the shutdown function (which is available on all platforms) I believe that we're fine in this respect. There's no way for us to provide a 100% cross-platform semantics for every piece of behavior (including what's quoted here) but instead provide what the underlying OS provides.