TIP #332 Version 1.1: Half-Close for Bidirectional Channels

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes to extend the close/chan close commands to let them perform an unidirectional "half-close" on bidirectional channels.

Background

Bidirectional channels (sockets and command pipelines) allow Tcl to make an efficient use of a "filter process", by exchanging data back and forth over an abstract "single" channel.

However, this single channel abstraction comes with a too coarse-grained close primitive. Indeed, it closes both directions simultaneously, while it is often desirable to close "gracefully" the half-connection to the filter process, leaving the return path open. The effect of such a half-close is that the filter receives a bona fide EOF alone, without a nearly simultaneous SIGPIPE on its write end if it happens to be writing at that time. Moreover, if the filter is itself comprised of a pipeline of processes, some of which doing buffered I/O, then this graceful EOF may be the only way of flushing the chain and receiving back precious data.

This technique is supported by all modern OSes: for pipes there are actually two separate file descriptors/handles, and it suffices to close() the write side; for sockets, a single fd is used, but a specific syscall, shutdown(), brings back the ability to half-close. Hence it is fairly natural for a universal "OS glove" like Tcl to expose this universal feature.

Proposed Change

This TIP proposes to extend the close and twin brother chan close commands to take an optional extra "direction" argument, indicating a half-close on the substream going in that direction:

close channel ?read|write?

When the extra direction argument (which may be abbreviated) is given, first the OS-level half-close is performed: 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:

	set f [open |command r+]
	...
	close $f w ;# $f still exists
	...
	close $f r ;# now $f is gone

Also, a single-argument close on an already half-closed bi-channel is defined to just "finish the job", which allows to write blind cleanup procedures easily:

	if {[catch {
	  set f [open |command r+]
	  ...
	  close $f w
	  ...
	} err]} {
	  ...
	  close $f ;# close what's left
	}

In the case of a command pipeline, the child-reaping duty falls upon the shoulders of the last close or half-close, so that an error condition at this stage (like "Child exited abnormally") doesn't leak system resources.

Last, a half-close on an already closed half raises an error:

	set [open |command r+]
	close $f w
	close $f w
	==> channel "file3" wasn't opened for writing

And the same applies to wrong-sided unidirectional channels:

	set [open filename r]
	close $f w
	==> channel "file3" wasn't opened for writing

Rationale

The concept has gone full circle. From an initial half-close proposal