Choosing a Reactor and GUI Toolkit Integration

Overview

Twisted provides a variety of implementations of the twisted.internet.reactor. The specialized implementations are suited for different purposes and are designed to integrate better with particular platforms.

The epoll()-based reactor is Twisted's default on Linux. Other platforms use poll(), or the most cross-platform reactor, select().

Platform-specific reactor implementations exist for:

• Poll for Linux
• Epoll for Linux 2.6
• WaitForMultipleObjects (WFMO) for Win32
• Input/Output Completion Port (IOCP) for Win32
• KQueue for FreeBSD and Mac OS X
• CoreFoundation for Mac OS X

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.

Twisted currently integrates with the following graphical toolkits:

• GTK+ 2.0
• GTK+ 3.0 and GObject Introspection
• Tkinter
• wxPython
• Win32
• CoreFoundation
• PyUI

When using applications that are runnable using twistd, e.g. TACs or plugins, there is no need to choose a reactor explicitly, since this can be chosen using twistd's -r option.

In all cases, the event loop is started by calling reactor.run(). In all cases, the event loop should be stopped with reactor.stop().

IMPORTANT: installing a reactor should be the first thing done in the app, since any code that does from twisted.internet import reactor will automatically install the default reactor if the code hasn't already installed one.

Reactor Functionality

General Purpose Reactors

Select()-based Reactor

1
2
3
4
from twisted.internet import selectreactor
selectreactor.install()

from twisted.internet import reactor

Platform-Specific Reactors

Poll-based Reactor

1
2
3
4
from twisted.internet import pollreactor
pollreactor.install()

from twisted.internet import reactor

KQueue

The KQueue Reactor allows Twisted to use FreeBSD's kqueue mechanism for event scheduling. See instructions in the twisted.internet.kqreactor's docstring for installation notes.

1
2
3
4
from twisted.internet import kqreactor
kqreactor.install()

from twisted.internet import reactor

WaitForMultipleObjects (WFMO) for Win32

1
2
3
4
from twisted.internet import win32eventreactor
win32eventreactor.install()

from twisted.internet import reactor

Input/Output Completion Port (IOCP) for Win32

1
2
3
4
from twisted.internet import iocpreactor
iocpreactor.install()

from twisted.internet import reactor

Epoll-based Reactor

1
2
3
4
from twisted.internet import epollreactor
epollreactor.install()

from twisted.internet import reactor

GUI Integration Reactors

GTK+

Twisted integrates with PyGTK version 2.0 using the gtk2reactor. An example Twisted application that uses GTK+ can be found in doc/core/examples/pbgtk2.py.

GTK-2.0 split the event loop out of the GUI toolkit and into a separate module called glib. To run an application using the glib event loop, use the glib2reactor. This will be slightly faster than gtk2reactor (and does not require a working X display), but cannot be used to run GUI applications.

1
2
3
4
from twisted.internet import gtk2reactor # for gtk-2.0
gtk2reactor.install()

from twisted.internet import reactor

1
2
3
4
from twisted.internet import glib2reactor # for non-GUI apps
glib2reactor.install()

from twisted.internet import reactor

GTK+ 3.0 and GObject Introspection

Twisted integrates with GTK+ 3 and GObject through PyGObject's introspection using the gtk3reactor and gireactor reactors.

1
2
3
4
from twisted.internet import gtk3reactor
gtk3reactor.install()

from twisted.internet import reactor

1
2
3
4
from twisted.internet import gireactor # for non-GUI apps
gireactor.install()

from twisted.internet import reactor

GLib 3.0 introduces the concept of GApplication, a class that handles application uniqueness in a cross-platform way and provides its own main loop. Its counterpart GtkApplication also handles application lifetime with respect to open windows. Twisted supports registering these objects with the event loop, which should be done before running the reactor:

1
2
3
4
5
6
7
8
9
from twisted.internet import gtk3reactor
gtk3reactor.install()

from gi.repository import Gtk
app = Gtk.Application(...)

from twisted import reactor
reactor.registerGApplication(app)
reactor.run()

wxPython

As with Tkinter, the support for integrating Twisted with a wxPython application uses specialized support code rather than a simple reactor.

1
2
3
4
5
from wxPython.wx import *
from twisted.internet import wxsupport, reactor

myWxAppInstance = wxApp(0)
wxsupport.install(myWxAppInstance)

However, this has issues when running 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:

1
2
3
4
from twisted.internet import wxreactor
wxreactor.install()

from twisted.internet import reactor

Later, once a wxApp instance has been created, but before reactor.run() is called:

1
2
3
from twisted.internet import reactor
myWxAppInstance = wxApp(0)
reactor.registerWxApp(myWxAppInstance)

An example Twisted application that uses wxPython can be found in doc/core/examples/wxdemo.py.

CoreFoundation

Twisted integrates with PyObjC version 1.0. Sample applications using Cocoa and Twisted are available in the examples directory under doc/core/examples/threadedselect/Cocoa.

1
2
3
4
from twisted.internet import cfreactor
cfreactor.install()

from twisted.internet import reactor

Non-Reactor GUI Integration

Tkinter

The support for Tkinter doesn't use a specialized reactor. Instead, there is some specialized support code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from Tkinter import *
from twisted.internet import tksupport, reactor

root = Tk()

# Install the Reactor support
tksupport.install(root)

# at this point build Tk app as usual using the root object,
# and start the program with "reactor.run()", and stop it
# with "reactor.stop()".

PyUI

As with Tkinter, the support for integrating Twisted with a PyUI application uses specialized support code rather than a simple reactor.

1
2
3
from twisted.internet import pyuisupport, reactor

pyuisupport.install(args=(640, 480), kw={'renderer': 'gl'})

An example Twisted application that uses PyUI can be found in doc/core/examples/pyuidemo.py.