Author: Miguel Sofer <firstname.lastname@example.org> State: Final Type: Project Vote: Done Created: 13-Jul-2008 Post-History: Tcl-Version: 8.6
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.
Functions to be Exported
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 http://msofer.com:8080/wiki?name=NRE
An example of how the API is to be used can be found at http://msofer.com:8080/wiki?name=Exploiting\+NRE
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 http://msofer.com:8080/wiki?name=NRE\+short\+explanation
This document has been placed in the public domain.