TIP 609: Enhance Tcl_ThreadQueueEvent()

Author:         Christian Werner <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        06-August-2021
Keywords:       Tcl
Tcl-Version:	8.7
Tcl-Branch:     tip-609
Vote-Summary:   Accepted 4/0/1
Votes-For:      AK, JN, KW, SL
Votes-Against:  none
Votes-Present:  FV


This TIP proposes to add a new qualifier to the Tcl_ThreadQueueEvent() function in order to allow implicit thread wakeup on empty queue condition.


Most code using Tcl_ThreadQueueEvent() is immediately followed by a call to Tcl_ThreadAlert(). This involves more than one pass through a critical section locking the same process wide resource. By considering the queue state (the empty condition) on causing the underlying Tcl_AlertNotifier() which is the work horse of Tcl_ThreadAlert(), the Tcl_ThreadAlert() can be completely left out, and the critical section must be locked/unlocked only once instead of twice, reducing potential spurious wakeups.


The new qualifier TCL_QUEUE_ALERT_IF_EMPTY is added for Tcl_ThreadQueueEvent() eliminating the need to call Tcl_ThreadAlert() afterwards. This qualifier checks for the state of the event queue of the target thread and perform an implicit equivalent of Tcl_ThreadAlert() if the queue is empty at the begin of Tcl_ThreadQueueEvent(). It can be used in combination ('|') with the already existing qualifiers.


By using conditional compilation and preprocessor symbols it should be in most cases possible to allow for backward compatibility, e.g.

#if (TCL_MAJOR_VERSION > 8) || (TCL_MINOR_VERSION > 6) Tcl_ThreadQueueEvent(threadId, &event->header, TCL_QUEUE_TAIL|TCL_QUEUE_ALERT_IF_EMPTY); #else Tcl_ThreadQueueEvent(threadId, &event->header, TCL_QUEUE_TAIL); Tcl_ThreadAlert(threadId); #endif


This document has been placed in the public domain.