Check-in [90090d1fd8]

Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Describe TCL_IO_FAILURE and TCL_AUTO_LENGTH. Also describe the changes to ckalloc()/Tcl_Alloc() and friends.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:90090d1fd846e0752e085e3f60d15a4be0ed6e3fafc33ffc65215a6d225c95ba
User & Date: jan.nijtmans 2018-09-06 12:54:08
Context
2018-09-07
09:52
New TIP #515. Fix link in TIP #514. check-in: f75ee55997 user: jan.nijtmans tags: trunk
2018-09-06
12:54
Describe TCL_IO_FAILURE and TCL_AUTO_LENGTH. Also describe the changes to ckalloc()/Tcl_Alloc() and friends. check-in: 90090d1fd8 user: jan.nijtmans tags: trunk
2018-09-04
19:50
TIP 430 CFV by DKF check-in: 0b0fd53b6f user: dkf tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to tip/494.md.

27
28
29
30
31
32
33







34
35
36
37
38
39
40
41
42
43
44
..
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
  
  * Many functions, which have size parameters of type _int_ (but NOT _int *_) will change to type _size\_t_

  * All _ClientData_ type arguments will be changed to _void *_ arguments. This is actually the same type, but it prevents the need for type-casts in some situations.

  * Provide a compilation option -D_TCL\_8\_COMPAT_, which provides fully source compatibility. Using this option, extensions compile and run fine using either Tcl 8 or Tcl 9 headers.
    More explanation below.








On 32-bit platforms, this is all 100% upwards binary compatible, provided no _internal_ API is used (since some internal structs might have incompatible but externally invisible changes)

On 64-bit platforms, those changes cause binary incompatibility. Therefore the TCL_MAGIC value needs to change, so extensions compiled using Tcl 9 headers will not load in Tcl 8 and reverse.


# Implications

Although those changes are binary compatible on 32-bit platforms, there is a small potential source incompatibility.
There are 10 functions which previously had an _int_ return argument, which is changed to _size\_t_. This signed/unsigned change might lead to subtle difference in behavior.

................................................................................
If the return value of such function is directly used in a compare, this could lead to the use of an unsigned compare in stead of a signed compare.
If you compile your extension with -D_TCL\_8\_COMPAT_, those 10 functions will be changed to wrapper macro's which makes everything behave as if those functions return Tcl_WideInt. That's the easiest way to resolve this potential problem.

There are 2 other ways to make this change, which can do it without the use of the _TCL\_8\_COMPAT_ macro:

  * Add _1_ to the left and right hand side of the comparison. E.g. [as here](https://core.tcl.tk/tk/fdiff?v1=100235897e9cf359&v2=9cf86629040df0d3)

  * Don't compare to -1 using < or >, but only using == or !=. You can get rid of the (Tcl 8.x) compiler warnings using casts to _(size\_t)_, for Tcl-9-only compiles one of the casts is not necessary any more. E.g. [as here](https://core.tcl.tk/tk/fdiff?v1=207c608cec63f8f0&v2=e2e5d2322beea420)

Tk and [sqlite](http://cyqlite.sourceforge.net/cgi-bin/sqlite/info/17c148b94008df81) are already converted to make full use of TIP #494. Other extensions included with Tcl (e.g. tdbc) are unaffected.

# Implementation

The implementation of this TIP can be found in the [memory-API branch]
(https://core.tcl.tk/tcl/timeline?r=memory-API).

# Copyright

This document has been placed in the public domain.







>
>
>
>
>
>
>



|







 







|











27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
..
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
  
  * Many functions, which have size parameters of type _int_ (but NOT _int *_) will change to type _size\_t_

  * All _ClientData_ type arguments will be changed to _void *_ arguments. This is actually the same type, but it prevents the need for type-casts in some situations.

  * Provide a compilation option -D_TCL\_8\_COMPAT_, which provides fully source compatibility. Using this option, extensions compile and run fine using either Tcl 8 or Tcl 9 headers.
    More explanation below.

  * Provide 2 new macro's TCL\_IO\_FAILURE and TCL\_AUTO\_LENGTH, both equal to ((size_t)-1). They can help making extensions use the full 64-bit range with Tcl 9, which still compile with Tcl 8 as well (see below). 
    Tcl 8.7 will get those macro's too, but the value there is (-1)

  * The functions Tcl\_Alloc(), Tcl\_Free() (and friends) change to redirect to their debugging variants if the TCL\_MEM\_DEBUG is defined. So, Tcl\_Alloc() becomes the same as ckalloc(), ending the general confusion regarding the difference between those two groups of functions: Starting with Tcl 9.0 there is no difference anymore.
    ckalloc() and friends are deprecated starting with 9.0, but there are no plans to actually remove those and no deprecation warning will be given if extensions use it.


On 32-bit platforms, this is all 100% upwards binary compatible, provided no _internal_ API is used (since some internal structs might have incompatible but externally invisible changes)

On 64-bit platforms, those changes cause binary incompatibility. Therefore the TCL\_STUB\_MAGIC value needs to change, so extensions compiled using Tcl 9 headers will not load in Tcl 8 and reverse.


# Implications

Although those changes are binary compatible on 32-bit platforms, there is a small potential source incompatibility.
There are 10 functions which previously had an _int_ return argument, which is changed to _size\_t_. This signed/unsigned change might lead to subtle difference in behavior.

................................................................................
If the return value of such function is directly used in a compare, this could lead to the use of an unsigned compare in stead of a signed compare.
If you compile your extension with -D_TCL\_8\_COMPAT_, those 10 functions will be changed to wrapper macro's which makes everything behave as if those functions return Tcl_WideInt. That's the easiest way to resolve this potential problem.

There are 2 other ways to make this change, which can do it without the use of the _TCL\_8\_COMPAT_ macro:

  * Add _1_ to the left and right hand side of the comparison. E.g. [as here](https://core.tcl.tk/tk/fdiff?v1=100235897e9cf359&v2=9cf86629040df0d3)

  * Don't compare to -1 using < or >, but always to TCL\_IO\_FAILURE using == or != . E.g. [as here](https://core.tcl.tk/tk/info/abe0d3b121cbb12d)

Tk and [sqlite](http://cyqlite.sourceforge.net/cgi-bin/sqlite/info/17c148b94008df81) are already converted to make full use of TIP #494. Other extensions included with Tcl (e.g. tdbc) are unaffected.

# Implementation

The implementation of this TIP can be found in the [memory-API branch]
(https://core.tcl.tk/tcl/timeline?r=memory-API).

# Copyright

This document has been placed in the public domain.