<type>documentation</type>
<domain>debug</domain>
<id>debug-i-o-multiplexing</id>
<title>Debug Process I/O Multiplexing</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Wing alters the I/O environment in order to make it possible to keep the debug process
responsive while waiting for I/O, and to redirect I/O over the connection to the IDE. This
code mimics the environment found outside of the debugger, so any code that uses only
Python I/O does not need to worry about this change.

There are however several cases that can affect users that bypass Python I/O
by doing C-level I/O from within an extension module:

* C/C++ extension modules that use the C-level ``stdin`` or ``stdout`` will bypass Wing's
  debugger I/O environment. This means that output sent to C-level ``stdout`` will not be
  redirected to the IDE. Also, waiting on ``stdin`` in C or C++ code will make the debug
  process unresponsive to messages from the IDE, such as ``Pause`` and changes to
  breakpoints, until the debug process exits its wait state.
  
* Calling C-level ``stdin`` from multiple threads in a multi-threaded program may result
  in altered character read order when running under Wing's debugger.
  
* When debugging on Windows, calling C-level ``stdin``, even in a single-threaded program,
  can result in a race condition with Wing's I/O multiplexer that leads to out-of-order
  character reads. This is an unavoidable result of limitations on multiplexing keyboard 
  and socket I/O on this platform.

**Disabling I/O Multiplexing**

If you run into a problem with keyboard I/O in Wing's debugger, you should:

1) Turn off Wing's I/O multiplexer by unchecking the `Debugger > I/O > Use sys.stdin
   Wrapper <script:show_preferences_gui#prefname="debug.use-stdin-wrapper">`__ preference.
   
2) Turn on the `Debugger > I/O > Use External Console 
   <script:show_preferences_gui#prefname="debug.external-console">`__ preference. 
   See `External I/O Consoles <ref:debug/external-i-o-consoles>`__ for details.

Once that is done, I/O should work properly in the external console, but the debug process
will remain unresponsive to ``Pause`` or breakpoint changes from Wing whenever it is
waiting for input, either at the C/C++ or Python level.

~~~if WINGPRO:
Also, keyboard input invoked as a side effect of using the ``Debug Console`` in Wing Pro
will happen through unmodified ``stdin`` instead of within the ``Debug Console``, even
though command output will still appear there.
~~~
