TIP #322: Publish the NRE API
_____________________________________________________________________________
TIP:	322
Title:	Publish the NRE API
Version:	$Revision: 1.9 $
Authors:	Miguel Sofer <msofer@users.sourceforge.net>
State:	Final
Type:	Project
Tcl-Version:	8.6
Vote:	Done
Created:	Sun Jul 13 00:00:00 UTC 2008
Abstract
This TIP exposes an API to allow extension writers to take advantage of Tcl's Non-Recursive evaluation Engine.
Rationale
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)
Documentation
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.
Reference Implementation
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
Copyright
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows