Tcl Source Code

View Ticket
Login
Ticket UUID: 1723738
Title: make TclTransferResult() public
Type: Patch Version: TIP Implementation
Submitter: eriklns Created on: 2007-05-22 19:51:24
Subsystem: 45. Parsing and Eval Assigned To: dkf
Priority: 5 Medium Severity:
Status: Closed Last Modified: 2008-12-05 22:36:55
Resolution: Fixed Closed By: dkf
    Closed on: 2008-12-05 15:21:52
Description:
This is a plea for making the function TclTransferResult() in tclResult.c part of the public interface.

The feature is useful in cases where results need to be exchanged between interpreters, that cannot make a sensible use of the command alias mechanism to take care of the transfer of the interpreter result and/or error info. (The alias mechanism is limited to object commands only, and does not cover other arbitrary cases that affect the interpreter result or error info.)

To implement the feature request, I foresee the following effort:
- renaming to Tcl_TranferResult(). In the current situation, the function is not declared static already.
- add it to the stubs table.
- write documentation (to be added to the manual page for Tcl_CreateInterp or Tcl_SaveResult ?).
- ...

If this feature request is honoured, I am prepared to write (a draft version for) the documentation.

Erik Leunissen
User Comments: dgp added on 2008-12-05 22:21:00:
um, ok, while I pondered,
dkf went and did it.

dgp added on 2008-12-05 01:26:02:
Oops!  typo.  Will document on
the SaveResult.3 page.

dgp added on 2008-12-05 01:05:45:
I do appreciate the effort for
contributing the documentation, but
I'm going to rewrite it.  I don't want
to offend, but the contributed docs
are written from a Tcl 8.4 perspective,
and omit considerations of the return
options dictionary.

Even so, rewriting something is easier
than the terror of the blank page.

I plan to document Tcl_TransferResult()
on the SetResult.3 page.

dgp added on 2008-12-03 04:47:02:
The thread restrictions are worth
mentioning in the docs, though they
are nothing new.  It's part of Tcl's
apartment model that you should only
pass a (Tcl_Interp *) value to a Tcl_*
routine from the same thread where
that (Tcl_Interp *) value was originally
returned by Tcl_CreateInterp().  Since
the Tcl_TransferResult() routine takes
two (Tcl_Interp *) arguments, the usual
rule implies that both interps live in
the same thread.

eriklns added on 2007-12-14 03:26:13:
Logged In: YES 
user_id=113903
Originator: YES

About thread awareness (which Joe Mistachkin mentions): that is something that I didn't reckon with as I proposed this feature request. If it is an issue here, I immediately accept that as being true. There is just little I have to offer with respect to documentation, because thread-awareness is something that I have very little overview over and insight into. I do not judge myself capable of writing sensible documentation related to that aspect. Someone else would have to take over ...

mistachkin added on 2007-12-13 13:55:52:
Logged In: YES 
user_id=113501
Originator: NO


One thing that I noticed is that TclTransferResult implicitly assumes that _both_ interps are on the same thread.  Maybe this should be mentioned in the docs if this API is made public?

dkf added on 2007-08-31 21:14:12:

data_type - 310894

Logged In: YES 
user_id=79902
Originator: NO

TIP now created. See http://tip.tcl.tk/307.html

eriklns added on 2007-08-29 02:27:34:

File Added - 243235: Tcl_TransferResult.doc

Logged In: YES 
user_id=113903
Originator: YES

File Added: Tcl_TransferResult.doc

eriklns added on 2007-08-29 02:26:34:
Logged In: YES 
user_id=113903
Originator: YES

Hereby, I submit the TIP (file Tcl_TransferResult.TIP) and corresponding draft documentation (file Tcl_TransferResult.doc).

File Added: Tcl_TransferResult.TIP

eriklns added on 2007-08-29 02:26:33:

File Added - 243234: Tcl_TransferResult.TIP

msofer added on 2007-08-20 05:35:16:
Logged In: YES 
user_id=148712
Originator: NO

I do not see any problem myself; does such an api addition require a TIP?
Erik: please go ahead and submit the docs. I am sending a request for comments to tclcore: if there are no opinions against, we'll do it. Otherwise, it can go into the internal stubs.

dgp added on 2007-05-23 03:41:24:
Logged In: YES 
user_id=80530
Originator: NO


While this is considered, I'd make
a note that the implementation of
TclTransferResult is made up entirely[*]
of calls to Tcl's public interface, so
an extension already has all the pieces
needed to reproduce TclTransferResult
for itself.

[*] other than some optimization hackery.

Attachments: