TIP #312: Add More Link Types


TIP:312
Title:Add More Link Types
Version:$Revision: 1.9 $
Authors: Rene Zaumseil <r dot zaumseil at freenet dot de>
Larry W. Virden <lvirden at yahoo dot com>
State:Draft
Type:Project
Tcl-Version:8.7
Vote:Pending
Created:Saturday, 26 January 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 \0 terminated string. The \0 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 [1].

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.


Powered by Tcl[Index] [History] [Edit] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]

TIP AutoGenerator - written by Donal K. Fellows