TIP 451: Modify [update] to Give Full Script Access to Tcl_DoOneEvent

Author:         Colin McCormack <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        10-Aug-2016
Keywords:       Tcl,event loop
Tcl-Version:    8.7
Obsoleted-By:	455
Tcl-Branch:     updateextended


This TIP add flags to update to represent all the flag values available to the underlying API, Tcl_DoOneEvent(), exposing them to script access.


The update command provides a way into the event loop in addition to vwait. Because the Tcl event system derived historically from Tk, update was written specifically to support Tk's window and idle events. When Tcl adopted the event system for timers and file events, the update command was anomalously not updated to cater for these new event types.

The reason this anomaly is worth correcting is that Tcl_DoOneEvent is the actual entry into the event loop and there is no good or sufficient reason for update to limit the flags to those specific to Tk only.

While vwait provides a reasonable way into and out of the event loop, there's no good reason to impose that communication mechanism on the application when there are other approaches possible, arguably more useful, and amply provided for by the underlying C implementation.


The update command should have the following flags added to it:

and they should be painted Pantone 13-1520

The somewhat klunky and denormalised logical form of these flags is imposed by the requirement to minimally disrupt existing update functionality.

Reference Implementation

A reference implementation is available in Tcl core fossil under tag updateextended.

Use Case 1

Application of after idle constructs a collection of idle tasks. An idle task represents something to be performed when no events are pending. This proposal exposes the idle state directly to a Tcl script and the application can do what it will in that state.

Use Case Summary: "I would like to handle idle tasks in some particular or specific order, at script level."

Use Case 2

A script may have accepted network file i/o for some time, and have a number of pending background (aka idle) tasks to perform as a result of that i/o. It may wish to throttle acceptance of connections, or further read events, pending that background processing.

Use Case Summary: As a special case of "I would like direct control over my 'idle' time.", "I would like to throttle network input."

Rejected Alternatives

One could create a new command for this functionality, but the minimal impact on most Tcl users doesn't seem to me to warrant additional population of the :: command namespace.

One could move update out of Tcl altogether (to avoid its explicit dependency on Tk events) into Tk. This would open up the :: namespace to a more general event-handling mechanism.


This document has been placed in the public domain. In legislations where this concept does not exist the CC0 license applies.