TIP #322: Publish the NRE API


TIP:322
Title:Publish the NRE API
Version:$Revision: 1.9 $
Author:Miguel Sofer <msofer at users dot sourceforge dot net>
State:Final
Type:Project
Tcl-Version:8.6
Vote:Done
Created:Sunday, 13 July 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.

The next three functions provide the API to request an evaluation by the trampoline, after the caller returned:

Finally, there is a function to register a callback that the trampoline has to execute right after a requested evaluation, typically used for cleanup.

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.


Powered by Tcl[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]

TIP AutoGenerator - written by Donal K. Fellows