TIP #337: MAKE TCLBACKGROUNDEXCEPTION() PUBLIC 
================================================
 Version:      $Revision: 1.6 $
 Author:       Don Porter <dgp_at_users.sf.net>
 State:        Final
 Type:         Project
 Tcl-Version:  8.6
 Vote:         Done
 Created:      Tuesday, 21 October 2008
 URL:          https://tip.tcl-lang.org337.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes to make the /TclBackgroundException/ routine 
 available in the public interface so that extensions may notify Tcl 
 about all return codes that occur during background operations. 

 BACKGROUND 
============

 When background operations in Tcl result in a non-*TCL_OK* return code, 
 it has been recommended practice to call /Tcl_BackgroundError()/ so 
 that Tcl can arrange for background error handlers to react to the 
 exceptional situation. The prototype of that routine is: 

       void *Tcl_BackgroundError*(Tcl_Interp */interp/) 

 In Tcl 8.5, the new *interp bgerror* command permits registration of 
 handlers that receive the full return options dictionary as an argument 
 [TIP #221]. This means that such handlers can respond differently to 
 different exceptions. At the same time a new internal routine 
 *TclBackgroundException* with prototype: 

       void *TclBackgroundException*(Tcl_Interp */interp/, int /code/) 

 and the implementation of *Tcl_BackgroundError* became: 

   void Tcl_BackgroundError(Tcl_Interp *interp) {
       TclBackgroundException(interp, TCL_ERROR);
   }

 The new *TclBackgroundException* routine is a more general routine 
 suitable for announcing any exceptional code returned by background 
 operations, not limited to *TCL_ERROR* like *Tcl_BackgroundError* has 
 been. The new *TclBackgroundException* routine is used throughout the 
 internal portions of Tcl so that full exception information gets 
 reliably passed through to background exception handlers, when the 
 background processing is governed by things which are built in to Tcl, 
 such as *after* and *chan event*. 

 The oversight of [TIP #221] was not proposing to make 
 *TclBackgroundException* public at the same time, so that extensions 
 which govern background operations, notably Tk, have access to the same 
 full expressive power. 

 PROPOSAL 
==========

 Rename the internal routine *TclBackgroundException* to 
 *Tcl_BackgroundException* and place it in the public stubs table. 

 Apply Tk Patch 1789752 
 [<URL:https://sourceforge.net/support/tracker.php?aid=1789752>] to make 
 use of the new facility. 

 COMPATIBILITY 
===============

 No compatibility concerns from a new public routine. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows