<type>documentation</type>
<domain>debug</domain>
<id>non-python-mainloops</id>
<title>Debugging Non-Python Mainloops</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

The debug process connects to the IDE using a TCP/IP socket which is serviced from the
debug tracer. Since Python only calls the tracer when Python byte codes are being
executed, the debug process may become unresponsive if it spends long periods of time in
non-Python code, such as in a C or C++ event loop. In this case, messages from Wing, such
as ``Pause`` or changes to breakpoints, will be ignored by the debug process until some
Python code is run again.

This is rarely an issue in practice since most code calls Python code periodically, and
Wing's debugger contains hooks that entirely avoid the problem in PyQt, Gtk, Tkinter,
wxPython, and Zope.

In the rare cases where the problem does occur, simple work-arounds include:  (1) Schedule 
some Python code to run periodically as an idle task or timeout, or (2) just don't try to
``Pause`` or change breakpoints while the debug process is busy.

An alternative is to write a plug-in that services the debugger's sockets even when no
Python code is being called, as described below.

**Writing Non-Python Mainloop Support**

Wing provides an API for adding the hooks necessary to ensure that the debugger's network
sockets are serviced at all times. In order to use this, you must be able to register the
debugger's socket in your environment's mainloop, or cause your mainloop to call
``select()`` on the socket periodically and invoke a provided callback when there is
activity on the socket.

Mainloop hooks are written as separate modules that are placed into ``src/debug/tserver``
in your Wing installation directory (on OS X, this is inside ``Contents/Resources`` in 
Wing's ``.app`` folder).  This directory contains several examples that can be used
as a starting point.

To add your own non-Python mainloop support, you must:

1) Copy one of the source examples, such as ``_gtkhooks.py``, to a file name 
   ``_xxxxhooks.py`` where ``xxxx`` is the name of your non-Python mainloop environment.
   
2) Determine the names of indicator modules Wing can used to identify that this
   mainloop environment is being loaded and set ``kIndicatorModuleName``.
   
3) Implement the ``_Setup()``, ``RegisterSocket()``, and ``UnregisterSocket()`` methods.
   Do not alter any code from the examples except the code within the methods. The name of
   the classes and constants at the top level of the file must remain the same.
   
4) Add the name of your module, minus the ``'.py'`` to the list ``kSupportedMainloops`` 
   in ``_extensions.py``

Don't hesitate to contact support@wingware.com if you need help.
