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 very close to the current one, an ambitious chan split generalization was born in the surrounding enthusiasm, and specified in TIP #301. Then, TIP #304's chan pipe was accepted, which addressed most of the "splitting" demand (asymmetric fconfigures on both ends of a command pipeline can be done by redirecting to a standalone pipe). Moreover, in hindsight it appears that the implementation of TIP #301 had very long-ranging effects on various channel implementations, which are more numerous today than before (TLS, reflection API).

As a consequence, TIP #301 is being withdrawn, and the current TIP goes back to its initial, lower profile: just provide the half-close.

Reference Implementation

Coming soon, once identified the best way of minimizing the channel ABI compatibility issue (since the half-close has to cross the generic channel interface).

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.