TIP 322: Publish the NRE API

Login
Author:         Miguel Sofer <[email protected]>
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 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.