TIP #307: Make TclTransferResult() Public

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:

• 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.doc (see [1]). 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.

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