TIP #285 Version 1.10: Script Cancellation with [interp cancel] and Tcl_CancelEval

This is not necessarily the current version of this TIP.

Title:Script Cancellation with [interp cancel] and Tcl_CancelEval
Version:$Revision: 1.10 $
Authors: Joe Mistachkin <joe at mistachkin dot com>
Dawson Cowals <dawson at dawsoncowals dot com>
Created:Sunday, 04 June 2006
Keywords:eval, cancel, unwind, terminate, runaway, async, thread, safe


This TIP introduces the ability to quickly and safely cancel a script within a specified interpreter from any thread in the process.

Key Use-Case Scenario

When using Tcl inside a context such as a web-browser (e.g. as a plugin), it is often necessary for the execution of a particular script to be terminated cleanly without waiting for the script to get to a point where it is able to respond to events. For example, if the user encounters a page that contains a script that starts a long-running execution but then decides to navigate away from the page, it's important to stop the script as soon as possible.

But we do not want to stop the script by means of just terminating the thread, as this can result in various resources being still allocated, as browsers are long-running applications. Some of the problems (e.g. memory waste) can be worked around by running the script in a separate process, but there are other resources that aren't cleaned up that way, such as locked files or shared memory blocks, and it is always better to give the Tcl interpreter itself an opportunity to clean up after itself. Furthermore, there are other possible applications (such as using Tcl to implement COM objects on Windows) where the separate-process method will not work so well.

Instead, what is needed is a way to programmatically make a script stop its execution even when that script is otherwise determined to continue. This is different from a resource limit in that the cancellation is not caused by the exceeding of a predetermined value, but rather by some external event that is possibly even not processed initially by Tcl at all.

Technical Rationale

Currently, once the evaluation of a script has been initiated it will do one of the following:

In each of the cases above, neither the host application nor an interactive user have any recourse to terminate the script prior to it running its course.

There are many situations for which it is absolutely necessary to be able to cancel a running script without its cooperation and without setting an arbitrary limit on the amount of time it can run (TIP #143). This is especially true in a multi-threaded application embedding environment, or where a user interface is present.

  1. In the case where the completion time for a script is unknown, non-existent, or non-deterministic a user may want or need to terminate the script prematurely.

  2. When evaluating an untrusted - or marginally trusted - script in either a safe or standard interpreter, there is a risk that the script might never terminate. In such a situation it is not reasonable to forcibly terminate the thread or the entire process.

    1. Forcibly terminating a thread prevents Tcl and Tk from cleaning up their thread-specific memory and resources.

    2. The host application may suffer similar memory and resource leaks as well as other serious side-effects that may corrupt data, prevent other threads from properly synchronizing, or leave the process in an unknown and unrecoverable state.

    3. For an interactive host application valuable work may be lost without providing an opportunity to save pending modifications. Even in the absence of modifications the host application might have been holding locks that left unreleased would prevent other processes and users from using important resources.

The basic building blocks needed for any scripting language to seamlessly integrate with an enterprise-ready host application are:

Tcl now provides full support for all of the above except script cancellation. TIP #143 allows for scripts to be prematurely terminated after reaching resource limits that were pre-arranged by the host application. However, this only handles terminating scripts based on a narrow set of deterministic criteria. Full support would require the ability to immediately and unconditionally terminate the evaluation of a script without adversely affecting the execution environment of the host application. In addition the following issues must be addressed:

Several other mainstream scripting engines (e.g., JavaScript, Microsoft Active Scripting, etc.) currently provide this capability to cancel the evaluation of a script. This TIP proposes an implementation that would bring this necessary aspect of application integration to Tcl. This must be implemented in the core, because access to and modification of internal Tcl functions and data structures is required.


A new interp cancel script command will be added, as follows:

interp cancel ?-unwind? ?--? ?path? ?result?

This command cancels the script being evaluated in the interpreter.



This argument is optional. Without -unwind, the evaluation stack for the interpreter is unwound until an enclosing catch command is found or there are no further invocations of the interpreter left on the call-stack. With -unwind, the evaluation stack for the interpreter is unwound without regard to any intervening catch command until there are no further invocations of the interpreter left on the call-stack.


This argument is optional, and marks the end of options. The argument following this one will be treated as being the path argument even if it starts with a "-".


This argument is optional. If not supplied, the current interpreter is assumed; otherwise, the interpreter specified by path is used.


This argument is optional. If not supplied, a default error message is left in the result of the interpreter; otherwise, the result specified by result is used.


When a script is canceled, the following occur: