Miguel Sofer$Revision: 1.9 $

This TIP exposes an API to allow extension writers to take advantage of Tcl's Non-Recursive evaluation Engine.

NRE (for Non-Recursive Engine) is a trampoline implementation for command evaluation and bytecode execution that massively reduce Tcl's footprint on the C stack. It is conceptually related to stackless Python. NRE is fully backwards compatible with script and C extensions and has already been committed to HEAD. Extensions that use the normal Tcl API run properly but cannot take advantage of the non-recursivity. This TIP proposes to publish a small API for extension writers that will allow them to exploit the new possibilities.

The first two functions permit the creation of NRE-enabled commands. Tcl_NRCreateCommand creates a command that implements an NRE interface nreProc. As every command needs also a regular objProc, the function Tcl_NRCallObjProc is provided as a utility permitting a relatively simple way to generate the objProc from the nreProc. Tcl_Command Tcl_NRCreateCommand(Tcl_Interp *interp, const char *cmdName, Tcl_ObjCmdProc *proc, Tcl_ObjCmdProc *nreProc, ClientData clientData, Tcl_CmdDeleteProc *deleteProc)int Tcl_NRCallObjProc(Tcl_Interp *interp, Tcl_ObjCmdProc *objProc, ClientData clientData, int objc, Tcl_Obj *const *objv[]) The next three functions provide the API to request an evaluation by the trampoline, after the caller returned: int Tcl_NREvalObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int flags)int Tcl_NREvalObjv(Tcl_Interp *interp, int objc, Tcl_Obj *const objv[], int flags)int Tcl_NRCmdSwap(Tcl_Interp *interp, Tcl_Command cmd, int objc, Tcl_Obj *const objv[]) Finally, there is a function to register a callback that the trampoline has to execute right after a requested evaluation, typically used for cleanup. void Tcl_NRAddCallback(Tcl_Interp *interp, Tcl_NRPostProc *postProcPtr, ClientData data0, ClientData data1, ClientData data2, ClientData data3)

NRE's internal functioning is somewhat documented at An example of how the API is to be used can be found at The new API will be documented in a manual page doc/NRE.3.

The API is already available in HEAD (to become Tcl8.6a2); a high level description is available at

This document has been placed in the public domain.