Author:         Jan Nijtmans <jan.nijtmans@gmail.com>
State:          Final
Type:           Project
Vote:           Done
Created:        31-Jan-2020
Post-History:
Tcl-Version:    8.7
Keywords:       Tcl
Tcl-Branch:     deprecate-channel-type-1-4
Vote-Summary:	Accepted 3/0/4
Votes-For:		DGP, DKF, JN
Votes-Against:	none
Votes-Present:	FV, KBK, KW, SL

Abstract

This TIP proposes to deprecate channel types 1-4, and remove it completely for Tcl 9.0. Only channels with type TCL_CHANNEL_VERSION_5 will be accepted by Tcl 9.0. Also, for Tcl 9.0, the seekProc and closeProc will no longer be used, wideSeekProc and close2Proc will be used in stead. Any Tcl 8.x channel with version TCL_CHANNEL_VERSION_5 implementing wideSeekProc (if it has seek functionalty) and close2Proc will be source-compatible with Tcl 9.0 and continue to work unchanged.

Proposal

In Tcl 9.0, the symbols TCL_CHANNEL_VERSION_1 up to TCL_CHANNEL_VERSION_4, and the symbol TCL_CLOSE2PROC, will be removed from tcl.h. All related code will be removed too. Besides, all core code calling the closeProc/seekProc will be modified to call close2Proc/wideSeekProc directly, without special version checks.

In Tcl 8.7, the symbols TCL_CHANNEL_VERSION_1 up to TCL_CHANNEL_VERSION_4 will be deprecated. The restriction in Tcl 8.6 that if wideSeekProc is available then seekProc must be available as well, will be lifted in Tcl 8.7. Also, the restriction that 'closeProc' must be available will be lifted in Tcl 8.7: NULL will have the same meaning as TCL_CLOSE2PROC.

Rationale and Discussion

The different channel versions allow various combination of functions implemented, all of those combinations need to be tested for and maintained. For example there is a closeProc and an close2Proc, there is a seekProc and a wideSeekProc. Let's clean-up that for Tcl 9.0 and make it simpler to be maintained.

For Tcl 9.0, if your channel has seek functionality, wideSeekProc needs to be implemented. seekProc will not be used any more. So, if you want to create a channel type that is source compatible with both Tcl 8.x and 9.0, either implement both seekProc and wideSeekProc either none of them. In Tcl 9.0 this restriction will be lifted, but Tcl 8.6 requires that if wideSeekProc is implemented seekProc should be implemented as well. We cannot change that any more in Tcl 8.6.

Further on, for Tcl 9.0 channels, close2Proc is required, closeProc will not be used any more.

Incompatibilities

All extensions using TCL_CHANNEL_VERSION_1 up to TCL_CHANNEL_VERSION_4 will not work any more in Tcl 9.0. Also channels which implement closeProc but not close2Proc, or seekProc but not wideSeekProc will not work as expected any more: They cannot be closed/cannot seek any more.

So any channel compatible with both Tcl 8.x and Tcl 9.0 needs to implement both closeProc and close2Proc. If your Tcl 8.6-compatible channel doesn't implement close2Proc yet, you can add a simple implementation as follows:

static int close2Proc(
    void *instanceData,
    Tcl_Interp *interp,
    int flags)
{
    if ((flags&(TCL_CLOSE_READ|TCL_CLOSE_WRITE))==0) {
        return closeProc(instanceData, interp);
    }
    return EINVAL;
}

Implementation

See branch deprecate-channel-type-1-4

Copyright