<type>documentation</type>
<domain>debug</domain>
<id>threading</id>
<title>Debugging Multi-threaded Code</title>
<date>$Date: 2007-05-09 16:44:39 -0400 (Wed, 09 May 2007) $</date>
<version>$Revision: 15504 $</version>
<product>all</product>

Wing's can debug multi-threaded code, as well as single-threaded code. When a debug
process has multiple threads, a thread selector popup is added to the stack selector area
at the top of the various debugger tools.

By default, Wing debugs all threads in a debug process, and will stop all threads
immediately if a single thread stops. Even though Wing tries to stop all threads, some may
continue running if they do not enter any Python code. In that case, the thread selector
will list the thread as running. It also indicates which thread was the first one to stop.

When moving among threads in a multi-threaded program, the ``Show Position`` icon that is
shown in the toolbar during debugging offers a convenient way to return to the original
thread and stopping position.

Whenever debugging threaded code, please note that the debugger's actions may alter the
order and duration that threads are run. This is a result of the small added overhead,
which may influence timing, and the fact that the debugger communicates with the IDE
through a TCP/IP connection.

**Selecting Threads to Debug**

To avoid stopping all threads in the debugger, you must launch the debug process from
outside Wing, import ``wingdbstub`` to initiate debug, and then use the debugger API's
``SetDebugThreads()`` call to specify which threads to debug. All other threads will be
entirely ignored. This is documented in `Debugging Externally Launched Code`__ and the API
is described in `Debugger API`__

__ ref:debug/debugging-externally-launched-code
__ ref:debug/debugger-api

Note, however, that specifying a subset of threads to debug may cause problems in some
code. For example, if a non-debugged thread starts running and does not return control to
any other threads, then the debug process will cease to respond to the IDE. This is
unavoidable since there is no way to preemptively force the debug-enabled threads to run
again.

