TIP:            322
Title:          Publish the NRE API
Version:        $Revision: 1.9 $
Author:         Miguel Sofer <msofer@users.sourceforge.net>
State:          Final
Type:           Project
Vote:           Done
Created:        13-Jul-2008
Post-History:   
Tcl-Version:    8.6

~ 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
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.