Attachment "Tcl_TransferResult.TIP" to
ticket [1723738fff]
added by
eriklns
2007-08-29 02:26:33.
TIP #XXX: MAKE TclTransferResult() PUBLIC
==========================================
Version: $Revision: $
Author: Erik Leunissen <e.leunissen_at_hccnet.nl>
State: Draft
Type: ??
Tcl-Version: ??
Vote:
Created: September 2007
URL: http://www.tcl.tk/cgi-bin/tct/tip/XXX.html
Post-History:
-------------------------------------------------------------------------
ABSTRACT
==========
This TIP proposes to make the existing function TclTransferResult() part of the public interface.
RATIONALE
===========
The function TclTransferResult() is used by Tcl internally to transfer the interp result and/or error info between different Tcl interpreters. Besides its use in the Tcl sources, applications (based on the Tcl library) which use multiple interpreters may have a need for this functionality as well. However, programmers are likely to overlook the existing TclTransferResult() as long as the function continues to lead its more or less hidden existence[*]. Making the function public is very much a matter of courtesy/generosity to programmers that use the Tcl library. It also seems to make the API's for result and error handling more complete.
[*] The TIP author discovered its existence only after bugs in his own code led him to inspect how Tcl internally handles result and error info between interpreters.
IMPLEMENTATION
================
There is not much to implement: TclTransferResult() already exists in tclResult.c.
What remains to be done:
* renaming to Tcl_TranferResult(): i.e. insert a single underscore character in its name. The function is not declared static already.
* slot it into the Tcl stubs table.
* write documentation
A draft version of the documentation has already been supplied as a separate file Tcl_TransferResult.ref It has been written as an addition to an existing man page. The question remains which is the most appropriate manual page to add it to.
Considerations for placement of the documentation:
- man page for Tcl_CreateInterp: this is the only manual page that is solely intended for multiple interpreters which are truly arbitrary interpreters, i.e. without any imposed relationship between them. However, it doesn't concern interp results.
- man page for Tcl_CreateSlave: this manual page says for itself that it concerns multiple interpreters, which is only half the truth: it concerns mostly interpreters that have an explicit master-slave relationship, the only exception being Tcl_CreateAlias(Obj).
- man page for Tcl_SaveResult: handles interp results (but is not at all intended for multiple interpreter situations)
COPYRIGHT
===========
This document has been placed in the public domain.
-------------------------------------------------------------------------
TIP AutoGenerator - written by Donal K. Fellows
