[TCLCORE] TIP #322: Publish the NRE API

[Miguel S. <ms...@us...>]

 TIP #322: PUBLISH THE NRE API 
===============================
 Version:      $Revision: 1.1 $
 Author:       Miguel Sofer <msofer_at_users.sourceforge.net>
 State:        Draft
 Type:         Project
 Tcl-Version:  8.6
 Vote:         Pending
 Created:      Sunday, 13 July 2008
 URL:          http://purl.org/tcl/tip/322.html
 WebEdit:      http://purl.org/tcl/tip/edit/322
 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 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. 
 *TclNR_CreateCommand* creates a command that implements an NRE 
 interface nreProc. As every command needs also a regular objProc, the 
 function *TclNR_CallObjProc* is provided as a utility permitting a 
 relatively simple way to generate the objProc from the nreProc. 

     * Tcl_Command *TclNR_CreateCommand*(Tcl_Interp */interp/, const 
       char */cmdName/, Tcl_ObjCmdProc */proc/, Tcl_ObjCmdProc 
       */nreProc/, ClientData /clientData/, Tcl_CmdDeleteProc 
       */deleteProc/) 

     * int *TclNR_CallObjProc*(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 *TclNR_EvalObj*(Tcl_Interp */interp/, Tcl_Obj */objPtr/, int 
       /flags/) 

     * int *TclNR_EvalObjv*(Tcl_Interp */interp/, int /objc/, Tcl_Obj 
       *const /objv/[], int /flags/) 

     * int *TclNR_ObjProc*(Tcl_Interp */interp/, Tcl_ObjCmdProc 
       */objProc/, ClientData /clientData/) 

 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 *TclNR_AddCallback*(Tcl_Interp */interp/, TclNR_PostProc 
       */postProcPtr/, ClientData /data0/, ClientData /data1/, 
       ClientData /data2/, ClientData /data3/) 

 DOCUMENTATION 
===============

 NRE's internal functioning is somewhat documented at 
 <URL:http://msofer.com:8080/wiki?name=NRE> 

 An example of how the API is to be used can be found at 
 <URL: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 
 <URL:http://msofer.com:8080/wiki?name=NRE+short+explanation> 

 COPYRIGHT 
===========

 This document has been placed in the public domain.  

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows