TIP #322: PUBLISH THE NRE API =============================== Version: $Revision: 1.9 $ Author: Miguel Sofer State: Final Type: Project Tcl-Version: 8.6 Vote: Done Created: Sunday, 13 July 2008 URL: https://tip.tcl-lang.org322.html Post-History: ------------------------------------------------------------------------- ABSTRACT ========== This TIP exposes an API to allow extension writers to take advantage of Tcl's Non-Recursive evaluation Engine. RATIONALE =========== NRE (for *N*on-*R*ecursive *E*ngine) 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/) DOCUMENTATION =============== 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/. REFERENCE IMPLEMENTATION ========================== The API is already available in HEAD (to become Tcl8.6a2); a high level description is available at COPYRIGHT =========== This document has been placed in the public domain. ------------------------------------------------------------------------- TIP AutoGenerator - written by Donal K. Fellows