choosing-reactor.html [plain text]
<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Choosing a Reactor and GUI Toolkit Integration</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Choosing a Reactor and GUI Toolkit Integration</h1><div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Reactor Functionality</a></li><li><a href="#auto2">General Purpose Reactors</a></li><ul><li><a href="#auto3">Select()-based Reactor</a></li><li><a href="#auto4">Poll()-based Reactor</a></li></ul><li><a href="#auto5">Platform-Specific Reactors</a></li><ul><li><a href="#auto6">cReactor for Unix</a></li><li><a href="#auto7">KQueue</a></li><li><a href="#auto8">Win32</a></li></ul><li><a href="#auto9">GUI Integration Reactors</a></li><ul><li><a href="#auto10">GTK+</a></li></ul><li><a href="#auto11">GUI Integration Reactors</a></li><ul><li><a href="#auto12">Cocoa</a></li><li><a href="#auto13">Qt</a></li></ul><li><a href="#auto14">Non-Reactor GUI Integration</a></li><ul><li><a href="#auto15">Tkinter</a></li><li><a href="#auto16">wxPython</a></li><li><a href="#auto17">PyUI</a></li></ul></ol></div><div class="content"><span></span><h2>Overview<a name="auto0"></a></h2><p>Twisted provides a variety of implementations of the <code class="API"><a href="http://twistedmatrix.com/documents/TwistedDocs/TwistedDocs-1.3.0/api/twisted.internet.reactor.html" title="twisted.internet.reactor">twisted.internet.reactor</a></code>. The specialized
implementations are suited for different purposes and are
designed to integrate better with particular platforms.</p><p>The general purpose reactor implementations are:</p><ul><li><a href="#select">The select()-based reactor</a></li><li><a href="#poll">The poll()-based reactor</a></li></ul><p>Platform-specific reactor implementations exist for:</p><ul><li><a href="#creactor">cReactor for Unix</a></li><li><a href="#kqueue">KQueue for FreeBSD</a></li><li><a href="#win32">Win32</a></li><li><a href="#cfreactor">Mac OS X</a></li></ul><p>The remaining custom reactor implementations provide support
for integrating with the native event loops of various graphical
toolkits. This lets your Twisted application use all of the
usual Twisted APIs while still being a graphical application.</p><p>Twisted currently integrates with the following graphical
toolkits:</p><ul><li><a href="#gtk">GTK+ 1.2 and 2.0</a></li><li><a href="#qt">Qt</a></li><li><a href="#tkinter">Tkinter</a></li><li><a href="#wxpython">WxPython</a></li><li><a href="#win32">Win32</a></li><li><a href="#cfreactor">Cocoa</a></li><li><a href="#pyui">PyUI</a></li></ul><p>When using applications that runnable using <code>twistd</code>, e.g.
TAPs or plugins, there is no need to choose a reactor explicitly, since
this can be chosen using <code>twistd</code>'s -r option.</p><p>In all cases, the event loop is started by calling <code class="python">reactor.run()</code>. In all cases, the event loop
should be stopped with <code class="python">reactor.stop()</code>.</p><p><strong>IMPORTANT:</strong> installing a reactor should be the first thing
done in the app, since any code that does
<code class="python">from twisted.internet import reactor</code> will automatically
install the default reactor if the code hasen't already installed one.</p><h2>Reactor Functionality<a name="auto1"></a></h2><table cellpadding="7" border="1" cellspacing="0" title="Summary of reactor features"><tr><td></td><th>TCP</th><th>SSL</th><th>UDP</th><th>Threading</th><th>Processes</th><th>Scheduling</th><th>Platforms</th></tr><tr><th>select()</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y (Unix only)</td><td>Y</td><td>Unix, Win32</td></tr><tr><th>poll()</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Unix</td></tr><tr><th>Win32</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Win32</td></tr><tr><th>cfreactor</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>OS X</td></tr><tr><th>GTK+</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y (Unix only)</td><td>Y</td><td>Unix, Win32</td></tr><tr><th>Qt</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y (Unix only)</td><td>Y</td><td>Unix, Win32</td></tr><tr><th>kqueue</th><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>Y</td><td>FreeBSD</td></tr><tr><th>C</th><td>Y</td><td>N</td><td>N</td><td>Y</td><td>Y</td><td>Y</td><td>Unix</td></tr></table><h2>General Purpose Reactors<a name="auto2"></a></h2><h3>Select()-based Reactor<a name="auto3"></a></h3><a name="select"></a><p>The SelectReactor is the default reactor.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">reactor</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><p>The SelectReactor may be explicitly installed by:</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">default</span><span class="py-src-newline">
</span><span class="py-src-variable">default</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h3>Poll()-based Reactor<a name="auto4"></a></h3><a name="poll"></a><p>The PollReactor will work on any platform that provides
<code class="python">poll()</code>. With larger numbers of
connected sockets, it may provide for better performance.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">pollreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">pollreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h2>Platform-Specific Reactors<a name="auto5"></a></h2><h3>cReactor for Unix<a name="auto6"></a></h3><a name="creactor"></a><p>The cReactor is a high-performance C implementation of the
Reactor interfaces. It is currently experimental and under
active development.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">cReactor</span><span class="py-src-newline">
</span><span class="py-src-variable">cReactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h3>KQueue<a name="auto7"></a></h3><a name="kqueue"></a><p>The KQueue Reactor allows Twisted to use FreeBSD's kqueue mechanism for
event scheduling. See instructions in the <code class="API"><a href="http://twistedmatrix.com/documents/TwistedDocs/TwistedDocs-1.3.0/api/twisted.internet.kqreactor.html" title="twisted.internet.kqreactor">twisted.internet.kqreactor</a></code>'s
docstring for installation notes.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">kqreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">kqreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h3>Win32<a name="auto8"></a></h3><a name="win32"></a><p>The Win32 reactor is not yet complete and has various limitations
and issues that need to be addressed. The reactor supports GUI integration
with the win32gui module, so it can be used for native Win32 GUI applications.
</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">win32eventreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">win32eventreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h2>GUI Integration Reactors<a name="auto9"></a></h2><h3>GTK+<a name="auto10"></a></h3><a name="gtk"></a><p>Twisted integrates with <a href="http://www.daa.com.au/~james/pygtk/">PyGTK</a>, versions 1.2 and 2.0. Sample applications using GTK+ and
Twisted are available in the Twisted CVS.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">gtkreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">gtkreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h2>GUI Integration Reactors<a name="auto11"></a></h2><h3>Cocoa<a name="auto12"></a></h3><a name="cfreactor"></a><p>Twisted integrates with <a href="http://pyobjc.sf.net/">PyObjC</a>, version 1.0. Sample applications using Cocoa and Twisted
are available in the examples directory under <code>Cocoa</code>.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">cfreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">cfreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h3>Qt<a name="auto13"></a></h3><a name="qt"></a><p>An example Twisted application that uses Qt can be found in
<code class="py-filename">doc/examples/qtdemo.py</code>.</p><p>When installing the reactor, pass a QApplication instance,
and if you don't a new one will be created for you.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">qt</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">QApplication</span><span class="py-src-newline">
</span><span class="py-src-variable">app</span> <span class="py-src-op">=</span> <span class="py-src-variable">QApplication</span><span class="py-src-op">(</span><span class="py-src-op">[</span><span class="py-src-op">]</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">qtreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">qtreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-variable">app</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><h2>Non-Reactor GUI Integration<a name="auto14"></a></h2><h3>Tkinter<a name="auto15"></a></h3><a name="tkinter"></a><p>The support for <a href="http://www.python.org/topics/tkinter/">Tkinter</a> doesn't use a specialized reactor. Instead, there is
some specialized support code:</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">Tkinter</span> <span class="py-src-keyword">import</span> <span class="py-src-op">*</span><span class="py-src-newline">
</span><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">tksupport</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-variable">root</span> <span class="py-src-op">=</span> <span class="py-src-variable">Tk</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-variable">root</span><span class="py-src-op">.</span><span class="py-src-variable">withdraw</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-comment"># Install the Reactor support
</span><span class="py-src-variable">tksupport</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-variable">root</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-comment"># at this point build Tk app as usual using the root object,
</span><span class="py-src-comment"># and start the program with "reactor.run()", and stop it
</span><span class="py-src-comment"># with "reactor.stop()".
</span><span class="py-src-endmarker"></span></pre><h3>wxPython<a name="auto16"></a></h3><a name="wxpython"></a><p>As with <a href="#tkinter">Tkinter</a>, the support for integrating
Twisted with a <a href="http://www.wxpython.org">wxPython</a>
application uses specialized support code rather than a simple reactor.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">wxPython</span><span class="py-src-op">.</span><span class="py-src-variable">wx</span> <span class="py-src-keyword">import</span> <span class="py-src-op">*</span><span class="py-src-newline">
</span><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">wxsupport</span><span class="py-src-op">,</span> <span class="py-src-variable">reactor</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-variable">myWxAppInstance</span> <span class="py-src-op">=</span> <span class="py-src-variable">wxApp</span><span class="py-src-op">(</span><span class="py-src-number">0</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-variable">wxsupport</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-variable">myWxAppInstance</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><p>However, this has issues when runnin on Windows, so Twisted now
comes with alternative wxPython support using a reactor. Using
this method is probably better. Initialization is done in two
stages. In the first, the reactor is installed:</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">wxreactor</span><span class="py-src-newline">
</span><span class="py-src-variable">wxreactor</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><p>Later, once a <code class="python">wxApp</code> instance has
been created, but before <code class="python">reactor.run()</code>
is called:</p><pre class="python">
<span class="py-src-variable">myWxAppInstance</span> <span class="py-src-op">=</span> <span class="py-src-variable">wxApp</span><span class="py-src-op">(</span><span class="py-src-number">0</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-variable">reactor</span><span class="py-src-op">.</span><span class="py-src-variable">registerWxApp</span><span class="py-src-op">(</span><span class="py-src-variable">myWxAppInstance</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><p>An example Twisted application that uses WxWindows can be found
in <code class="py-filename">doc/examples/wxdemo.py</code>.</p><h3>PyUI<a name="auto17"></a></h3><a name="pyui"></a><p>As with <a href="#tkinter">Tkinter</a>, the support for integrating
Twisted with a <a href="http://pyui.sourceforge.net">PyUI</a>
application uses specialized support code rather than a simple reactor.</p><pre class="python">
<span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span><span class="py-src-op">.</span><span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">pyuisupport</span><span class="py-src-op">,</span> <span class="py-src-variable">reactor</span><span class="py-src-newline">
</span><span class="py-src-nl">
</span><span class="py-src-variable">pyuisupport</span><span class="py-src-op">.</span><span class="py-src-variable">install</span><span class="py-src-op">(</span><span class="py-src-variable">args</span><span class="py-src-op">=</span><span class="py-src-op">(</span><span class="py-src-number">640</span><span class="py-src-op">,</span> <span class="py-src-number">480</span><span class="py-src-op">)</span><span class="py-src-op">,</span> <span class="py-src-variable">kw</span><span class="py-src-op">=</span><span class="py-src-op">{</span><span class="py-src-string">'renderer'</span><span class="py-src-op">:</span> <span class="py-src-string">'gl'</span><span class="py-src-op">}</span><span class="py-src-op">)</span><span class="py-src-newline">
</span><span class="py-src-endmarker"></span></pre><p>An example Twisted application that uses PyUI can bve found in <code class="py-filename">doc/examples/pyuidemo.py</code>.</p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 1.3.0</span></body></html>