<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE TIP SYSTEM "http://www.tcl.tk/cgi-bin/tct/tip/tipxml.dtd">
<!-- Converted at Sun Feb 12 12:31:56 GMT 2012 -->
<!-- TIP AutoGenerator - written by Donal K. Fellows -->

<TIP number='337'>
<header><title>Make TclBackgroundException() Public</title><author address="mailto:dgp@users.sf.net">Don Porter</author><status type='project' state='final' tclversion="8.6" vote='after'>$Revision: 1.6 $</status><history></history><created day='21' month='oct' year='2008' /></header>
<abstract>This TIP proposes to make the <emph style="italic">TclBackgroundException</emph> routine available in the public interface so that extensions may notify Tcl about all return codes that occur during background operations.</abstract>
<body><section title="Background">
<para>When background operations in Tcl result in a non-<emph style="bold">TCL_OK</emph> return code, it has been recommended practice to call <emph style="italic">Tcl_BackgroundError()</emph> so that Tcl can arrange for background error handlers to react to the exceptional situation. The prototype of that routine is:</para>
<quote>void <emph style="bold">Tcl_BackgroundError</emph>(Tcl_Interp *<emph style="italic">interp</emph>)</quote>
<para>In Tcl 8.5, the new <emph style="bold">interp bgerror</emph> command permits registration of handlers that receive the full return options dictionary as an argument <tipref type="text" tip="221"/>. This means that such handlers can respond differently to different exceptions. At the same time a new internal routine <emph style="bold">TclBackgroundException</emph> with prototype:</para>
<quote>void <emph style="bold">TclBackgroundException</emph>(Tcl_Interp *<emph style="italic">interp</emph>, int <emph style="italic">code</emph>)</quote>
<para>and the implementation of <emph style="bold">Tcl_BackgroundError</emph> became:</para>
<verbatim><vline encoding='base64'>dm9pZCBUY2xfQmFja2dyb3VuZEVycm9yKFRjbF9JbnRlcnAgKmludGVycCkgew==</vline><vline encoding='base64'>ICAgIFRjbEJhY2tncm91bmRFeGNlcHRpb24oaW50ZXJwLCBUQ0xfRVJST1IpOw==</vline><vline encoding='base64'>fQ==</vline></verbatim>
<para>The new <emph style="bold">TclBackgroundException</emph> routine is a more general routine suitable for announcing any exceptional code returned by background operations, not limited to <emph style="bold">TCL_ERROR</emph> like <emph style="bold">Tcl_BackgroundError</emph> has been. The new <emph style="bold">TclBackgroundException</emph> 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 <emph style="bold">after</emph> and <emph style="bold">chan event</emph>.</para>
<para>The oversight of <tipref type="text" tip="221"/> was not proposing to make <emph style="bold">TclBackgroundException</emph> public at the same time, so that extensions which govern background operations, notably Tk, have access to the same full expressive power.</para>
</section>
<section title="Proposal">
<para>Rename the internal routine <emph style="bold">TclBackgroundException</emph> to <emph style="bold">Tcl_BackgroundException</emph> and place it in the public stubs table.</para>
<para>Apply Tk Patch 1789752 [<url ref="https://sourceforge.net/support/tracker.php?aid=1789752"/>] to make use of the new facility.</para>
</section>
<section title="Compatibility">
<para>No compatibility concerns from a new public routine.</para>
</section>
<section title="Copyright">
<para>This document has been placed in the public domain.</para>
</section>
</body></TIP>

