<type>documentation</type>
<domain>debug</domain>
<id>process-control</id>
<title>Process Control</title>
<date>$Date: 2007-05-09 16:44:39 -0400 (Wed, 09 May 2007) $</date>
<version>$Revision: 15504 $</version>
<product>pro+</product>

When multi-process debugging is enabled, Wing will allow creation of multiple processes
from the ``Debug`` > ``Processes`` sub-menu. This menu also provides a way to continue,
pause, restart, or terminate all debug processes at once.

Pressing the ``Alt`` key while clicking on the ``Continue``, ``Terminate``, or ``Restart``
toolbar icons also causes the operation to be applied to all applicable debug processes at
once.

By default when a new process connects and reaches a breakpoint or exception, it is made
into the current debug process only if there is no previously current and paused debug
process, or if it is the first process that has stopped for the process group most
recently launched from the IDE (this does not include processes that attach using
wingdbstub unless they are in a process group started from the IDE). In other cases, Wing 
displays a message at the bottom of the IDE window indicating that a debug process has 
stopped but does not make it the current process.

This behavior can be changed using the `Debug > Processes > Switch to Stopped Processes
<script:show_preferences_gui#prefname="debug.multi-process-switch">`__ preference. Setting
this preference to ``Always Switch`` may be confusing if many processes are reaching a
stopping point at once.  However, this is the only way to automatically switch to a
debug process started with ``wingdbstub`` when another debug process is already active.

Wing also lets you control the maximum number of debug processes that may be attached to
the IDE at once using the `Debugger > Processes > Maximum Process Count
<script:show_preferences_gui#prefname="debug.multi-process-maximum">`__ preference.

**Terminating Processes**

When a debug process is terminated from Wing, the IDE will by default also terminate all
other processes in the process group. This is appropriate behavior in many but not all
cases. The `Debugger > Processes > Termination Model
<script:show_preferences_gui#prefname="debug.multi-process-kill-model">`__ preference
provides several options for managing termination of debug processes in a multi-processing
environment:

**Leave Other Processes Running** kills only the selected process and leaves all other
processes running.

**Kill Child Processes with Parent** also kills all children, grand-children, and other
processes spawned by the process that is being terminated. However, any parent,
grand-parents, uncles, cousins, etc, of the terminated process are left running.

**Kill Entire Process Group** kills all processes in the group, including all parents,
grand-parents, children, grand-children, uncles, cousins, etc. This is the default
termination model.
 
**Prompt for Action When a Process is Killed** displays a dialog listing processes
associated with the debug process that is being terminated and offers to kill selected
processes, all children, or the entire process group.

Note that when a only subset of the processes in a procress group are killed, those
remaining processes that expect to interact with one of the terminated processes may raise
"broken pipe" or similar errors.
