# 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 general purpose reactor implementations are:

- The select()-based reactor
- The poll()-based reactor

Platform-specific reactor implementations exist for:

- cReactor for Unix
- KQueue for FreeBSD
- Win32
- 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+ 1.2 and 2.0
- Qt
- Tkinter
- WxPython
- Win32
- Cocoa
- PyUI

When using applications that runnable using `twistd`, e.g. TAPs 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 hasen't already installed one.

## Reactor Functionality

| TCP | SSL | UDP | Threading | Processes | Scheduling | Platforms
select() | Y | Y | Y | Y | Y (Unix only) | Y | Unix, Win32
poll() | Y | Y | Y | Y | Y | Y | Unix
Win32 | Y | Y | Y | Y | Y | Y | Win32
cfreactor | Y | Y | Y | Y | Y | Y | OS X
GTK+ | Y | Y | Y | Y | Y (Unix only) | Y | Unix, Win32
Qt | Y | Y | Y | Y | Y (Unix only) | Y | Unix, Win32
kqueue | Y | Y | Y | Y | Y | Y | FreeBSD
C | Y | N | N | Y | Y | Y | Unix

## General Purpose Reactors

### Select()-based Reactor

The SelectReactor is the default reactor.

    from twisted.internet import reactor

The SelectReactor may be explicitly installed by:

    from twisted.internet import default
    default.install()

### Poll()-based Reactor

The PollReactor will work on any platform that provides `poll()`. With larger numbers of connected sockets, it may provide for better performance.

    from twisted.internet import pollreactor
    pollreactor.install()

## Platform-Specific Reactors

### cReactor for Unix

The cReactor is a high-performance C implementation of the Reactor interfaces. It is currently experimental and under active development.

    from twisted.internet import cReactor
    cReactor.install()

### 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.

    from twisted.internet import kqreactor
    kqreactor.install()

### Win32

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.

    from twisted.internet import win32eventreactor
    win32eventreactor.install()

## GUI Integration Reactors

### GTK+

Twisted integrates with PyGTK, versions 1.2 and 2.0. Sample applications using GTK+ and Twisted are available in the Twisted CVS.

    from twisted.internet import gtkreactor
    gtkreactor.install()

## GUI Integration Reactors

### Cocoa

Twisted integrates with PyObjC, version 1.0. Sample applications using Cocoa and Twisted are available in the examples directory under `Cocoa`.

    from twisted.internet import cfreactor
    cfreactor.install()

### Qt

An example Twisted application that uses Qt can be found in `doc/examples/qtdemo.py`.

When installing the reactor, pass a QApplication instance, and if you don't a new one will be created for you.

    from qt import QApplication
    app = QApplication([])

    from twisted.internet import qtreactor
    qtreactor.install(app)

## Non-Reactor GUI Integration

### Tkinter

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

    from Tkinter import *
    from twisted.internet import tksupport

    root = Tk()
    root.withdraw()

    # 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()".

### wxPython

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

    from wxPython.wx import *
    from twisted.internet import wxsupport, reactor

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

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:

    from twisted.internet import wxreactor
    wxreactor.install()

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

    myWxAppInstance = wxApp(0)
    reactor.registerWxApp(myWxAppInstance)

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

### PyUI

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

    from twisted.internet import pyuisupport, reactor

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

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