TIP #332 IMPLEMENTATION - Half-Close for Bidirectional Channels

1 files changed, 15 insertions, 5 deletions

diff --git a/doc/close.n b/doc/close.n
index 800ee8a..c4b1612 100644
--- a/doc/close.n
+++ b/doc/close.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: close.n,v 1.14 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: close.n,v 1.15 2008/12/18 01:14:16 ferrieux Exp $
 '\" 
 .so man.macros
 .TH close n 7.5 Tcl "Tcl Built-In Commands"
@@ -14,19 +14,20 @@
 .SH NAME
 close \- Close an open channel
 .SH SYNOPSIS
-\fBclose \fIchannelId\fR
+\fBclose \fIchannelId\fR ?r(ead)|w(rite)?
 .BE
 
 .SH DESCRIPTION
 .PP
-Closes the channel given by \fIchannelId\fR.
+Closes or half-closes the channel given by \fIchannelId\fR.
 .PP
 \fIChannelId\fR must be an identifier for an open channel such as a
 Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
 the result of a channel creation command provided by a Tcl extension.
 .PP
-All buffered output is flushed to the channel's output device,
+The single-argument form is a simple "full-close":
+all buffered output is flushed to the channel's output device,
 any buffered input is discarded, the underlying file or device is closed,
 and \fIchannelId\fR becomes unavailable for use.
 .PP
@@ -56,6 +57,15 @@ The command returns an empty string, and may generate an error if
 an error occurs while flushing output.  If a command in a command
 pipeline created with \fBopen\fR returns an error, \fBclose\fR
 generates an error (similar to the \fBexec\fR command.)
+.PP
+The two-argument form is a "half-close": given a bidirectional channel like a socket or command pipeline and a (possibly abbreviated) direction, it closes only the substream going in that direction. This means a shutdown() on a socket, and a close() of one end of a pipe for a command pipeline. Then, the Tcl-level channel data structure is either kept or freed depending on whether the other direction is still open.
+.PP
+A single-argument close on an already half-closed bi-channel is defined to just "finish the job. A half-close on an already closed half, or on a wrong-sided unidirectional channel, raises an error.
+.PP
+In the case of a command pipeline, the child-reaping duty falls upon the shoulders of the last close or half-close, which is thus allowed to report an abnormal exit error.
+.PP
+Currently only sockets and command pipelines support half-close. A future extension will allow reflected and stacked channels to do so.
+
 .SH EXAMPLE
 .PP
 This illustrates how you can use Tcl to ensure that files get closed
@@ -76,4 +86,4 @@ proc withOpenFile {filename channelVar script} {
 .SH "SEE ALSO"
 file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
 .SH KEYWORDS
-blocking, channel, close, nonblocking
+blocking, channel, close, nonblocking, half-close