TIP #322 Version 1.5: Publish the NRE API

This is not necessarily the current version of this TIP.

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.

This is not necessarily the current version of this TIP.