TIP #312: Add More Link Types
_____________________________________________________________________________
TIP:	312
Title:	Add More Link Types
Version:	$Revision: 1.9 $
Authors:	Rene Zaumseil <r.zaumseil@freenet.de>
	Larry W. Virden <lvirden@yahoo.com>
State:	Draft
Type:	Project
Tcl-Version:	8.7
Vote:	Pending
Created:	Sat Jan 26 00:00:00 UTC 2008
Keywords:	variable, trace
Abstract
This TIP proposes adding a command, Tcl_LinkArray, to allow linking of C variables to Tcl lists. It also adds more types of linked variable.
Rationale
The current C-API allows one to only link single variables. The proposed Tcl_LinkArray function allows the linking of C-arrays to Tcl list variables. If the given size value is 1 then it works like the existing Tcl_LinkVar function. The automatic creation of needed space when no address value is provided could be used for testing scenarios.
The new link types also allow one to link from strings and binary arrays to fixed memory locations.
The use of arrays with a given size > 1 allows a safe and simple C-Tcl connection. Array overwrites create errors.
Specification
This document proposes the following changes to the Tcl core:
New C API
Add a new public Tcl_LinkArray function to provide links of single variable and array variables. The new function would have the same parameters as the Tcl_LinkVar function, plus an additional int size. If the given size is 1, then we have the same functionality as before. With size > 1, the linked Tcl variable is a list variable. If the given address is NULL then the function allocates the necessary space on the C side itself.
int Tcl_LinkArray(Tcl_Interp *interp, const char *varName, char *addr, int type, int size)
The following link types will be supported:
TCL_LINK_INT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, TCL_LINK_STRING, TCL_LINK_WIDE_INT, TCL_LINK_CHAR, TCL_LINK_UCHAR, TCL_LINK_SHORT, TCL_LINK_USHORT, TCL_LINK_UINT, TCL_LINK_LONG, TCL_LINK_ULONG, TCL_LINK_FLOAT, TCL_LINK_WIDE_UINT, TCL_LINK_CHARS, TCL_LINK_BINARY
Of these, TCL_LINK_CHARS and TCL_LINK_BINARY are new, and are as defined below:
TCL_LINK_CHARS	The address of the C variable is used as a char *. The address remains always the same (different to TCL_LINK_STRING) and contains a  terminated string. The  counts towards the given size. The Tcl variable is used as a string and can contain up to size -1 characters.
TCL_LINK_BINARY	The address of the C variable is used as a unsigned char *. The address remains always the same. Read and write operations must always contain the full sized binary string.
Reference Implementation
See [https://sourceforge.net/support/tracker.php?aid=1992824].
Notes
The original TIP proposed a link command to allow these things to be done from the script level; this has been removed in the test suite support because of concerns about safety and security.
Copyright
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows