# TIP 562: Deprecate channel types 1-4
	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:

<pre>
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;
}
</pre>

# Implementation

See branch _deprecate-channel-type-1-4_

# Copyright

This document has been placed in the public domain. 
