TIP 307: Make TclTransferResult() Public

Login
Author:		Erik Leunissen <[email protected]>
State:		Final
Type:		Project
Tcl-Version:	8.6
Vote:		Done
Created:	28-Sep-2007
Post-History:	
Keywords:	Tcl, result, transfer, interpreter, API rename
Tcl-Ticket:     1723738

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 an interpreter result and/or error information 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. (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.) 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.

This TIP does not propose to change either the arguments or semantics of the function.

Implementation

There is not much to implement: TclTransferResult() already exists in tclResult.c. What remains to be done:

A draft version of the documentation has already been supplied as a separate file Tcl_TransferResult.doc (see http://sf.net/support/tracker.php?aid=1723738 ). 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:

Copyright

This document has been placed in the public domain.