Don Porter$Revision: 1.7 $

This TIP proposes the new public routine Tcl_NRExprObj to provide extension commands that evaluate Tcl expressions the ability to do so in a non-recursive manner.

In a few contexts, expressions that contain yield raise the error "cannot yield: C stack busy"; see Tcl Bugs 2823282 [] and 2823276 []. This is because a few little-visited corners of Tcl's implementation call the routine Tcl_ExprObj and that routine is not NR-enabled. For extensions wishing to evaluate Tcl expressions, Tcl_ExprObj is not little-visited. It is the public, supported, recommended tool for the job. Just as provided a routine Tcl_NREvalObj as an NR-enabled replacement for Tcl_EvalObj, extensions wishing to NR-enable their commands need an analogous replacement for Tcl_ExprObj.

Tcl has a long history of providing extensions access to the same capabilities available to the built-in command set so that extension commands are on an equal footing, not in a second class status. Keeping with that, we want extensions to be able to create NR-enabled commands, so we need to provide an interface for extensions to evaluate expressions in an NR-enabled manner. This TIP can be seen as filling up a hole in .

The Tcl public C interface provides a whole family of variants of Tcl_ExprObj: Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString. NR-enabled counterparts to these routines are not proposed. Extensions rewriting their command procedures to use the proposed Tcl_NRExprObj for sake of NR-enabling can at the same time be expected to convert from these convenience wrappers to more direct use of a single NR-enabled primitive.

Add the following routine to Tcl's public interface: int Tcl_NRExprObj(Tcl_Interp *interp, Tcl_Obj *objPtr, Tcl_Obj *resultPtr) This routine places on the NR stack a request that the Tcl non-recursive trampoline evaluate the objPtr value as a Tcl expression in interpreter interp. This routine returns the value TCL_OK, since there is (currently) no way this request operation can fail. The proposed interface still provides for an int return value so that future revisions to Tcl's internals have the freedom to change that without need to change the public interface. The resultPtr argument must be an unshared Tcl value. When expression evaluation succeeds, the result of the expression is written to resultPtr in the same way that Tcl_SetStringObj would write a string value to an unshared Tcl value. If expression evaluation produces any return code other than TCL_OK, the value of resultPtr is left untouched. Callers of Tcl_NRExprObj will also need to call Tcl_NRAddCallback to request a Tcl_NRPostProc callback routine be placed on the NR stack which can take care of managing resultPtr as appropriate depending on the result value.

The patch attached to Tcl Bug 2823282 [] implements this proposal.

There should be no compatibility issues, since at the interface level this is just the addition of a new routine. Revisions to the internal implementations of existing routines should be harmless.

As an example for extensions to follow, consider this template for a Tcl_ObjCmdProc currently calling Tcl_ExprObj. aW50IE9iakNtZChDbGllbnREYXRhIGNkLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBvYmpjLCBUY2xfT2JqICpjb25zdCBvYmp2W10peyAgIGludCBjb2RlOw==ICAgIFRjbF9PYmogKnJlc3VsdFB0cjs=ICAgIC8qIGRldGVybWluZSBleHByZXNzaW9uLCBvYmpQdHIgKi8=ICAgIGNvZGUgPSBUY2xfRXhwck9iaihpbnRlcnAsIG9ialB0ciwgJnJlc3VsdFB0cik7ICAgIGlmIChjb2RlICE9IFRDTF9PSykge3JldHVybiBjb2RlfQ==ICAgIC8qIHJlc3VsdFB0ciBob2xkcyBleHByZXNzaW9uIHJlc3VsdDsgY29udGludWUgKi8=fQ==VGNsX0NyZWF0ZU9iakNvbW1hbmQoaW50ZXJwLCBuYW1lLCBPYmpDbWQsIC8qIC4uLiAqLyk7 To use Tcl_NRExprObj to NR-enable this command, rewrite along these lines: aW50IE9iakNtZChDbGllbnREYXRhIGNkLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBvYmpjLCBUY2xfT2JqICpjb25zdCBvYmp2W10peyAgIHJldHVybiBUY2xfTlJDYWxsT2JqUHJvYyhpbnRlcnAsIE5ST2JqQ21kLCBjZCwgb2JqYywgb2Jqdik7ICB9aW50IE5ST2JqQ21kKENsaWVudERhdGEgY2QsIFRjbF9JbnRlcnAgKmludGVycCwgaW50IG9iamMsIFRjbF9PYmogKmNvbnN0IG9ianZbXSk=eyAgIFRjbF9PYmogKnJlc3VsdFB0ciA9IFRjbF9OZXdPYmooKTs=ICAgIC8qIGRldGVybWluZSBleHByZXNzaW9uLCBvYmpQdHIgKi8=ICAgIFRjbF9OUkFkZENhbGxiYWNrKGludGVycCwgQ2FsbGJhY2ssIHJlc3VsdFB0ciwgLyouLi4qLyk7ICAgIHJldHVybiBUY2xfTlJFeHByT2JqKGludGVycCwgb2JqUHRyLCByZXN1bHRQdHIpOw==fQ==aW50IENhbGxiYWNrKENsaWVudERhdGEgZGF0YVtdLCBUY2xfSW50ZXJwICppbnRlcnAsIGludCBjb2RlKQ==eyAgIFRjbF9PYmogKnJlc3VsdFB0ciA9IGRhdGFbMF07ICAgIGlmIChjb2RlICE9IFRDTF9PSykge1RjbF9EZWNyUmVmQ291bnQocmVzdWx0UHRyKTsgcmV0dXJuIGNvZGU7fQ==ICAgIC8qIHJlc3VsdFB0ciBob2xkcyBleHByZXNzaW9uIHJlc3VsdDsgY29udGludWUgKi8=fQ==VGNsX05SQ3JlYXRlQ29tbWFuZChpbnRlcnAsIG5hbWUsIE9iakNtZCwgTlJPYmpDbWQsIC8qLi4uKi8pOw==

This document has been placed in the public domain.