Applications and Services

A Twisted program, at its core, consists of a global application object holding a tree of available services.

What is a Twisted Application?

  Class: twisted.application.service.Application

An Application object is a persistent configuration object, constructed by the mktap command and which is then queried and acted upon by the program runtime. This object usually holds all persistent configuration of a running server -- ports to bind to, places where connections to must be kept or attempted, periodic actions to do and almost everything else. It is the root object in a tree of services implementing IService.

Applications are just Python objects, which can be created and manipulated in the same ways as any other object. In particular, they can be serialized to files.

Twisted applications are designed, instantiated, started up, shut down and packaged. They appear on disk as persistent objects stored within a .tap file. The act of instantiating an application object is the act of configuring it. There is no separate configuration file per se. A single Twisted application may be made up of one or more servers.

Application objects export four interfaces:

• IService
• IServiceCollection
• IProcess
• twisted.persisted.sob.IPersistable

Creating

Instantiating (Configuring) a Twisted Application object

Instances of Twisted Application objects are created with the mktap command-line tool. Application objects can be created based on any of several existing Application classes (web, ftp, ...), or custom Application classes, of which mktap is made aware of through the TwistedPlugin? architecture.

  mktap [options] <appclassname> [appclass options]

Creating an instance does not start the application running but rather writes a file out encapsulating the configuration.

Starting

To start an application running, the twistd command is used:

  twistd ...

The ''twistd' program unserializes the application, gets the IService? component, calls startService, schedules stopService when the reactor shuts down, and then calls reactor.run(). The program takes many command-line options, readable via --help.

Stopping

When a Twisted Application starts running, it records its process id in a twistd.pid file (this can be configured via a command line switch). In order to shutdown the twistd process, kill that pid:

  kill `cat twisted.pid`

When the process is killed in an orderly fashion it will leave behind the shutdown Application which is named the same as the original file with a -shutdown added to its base name. This contains the new configuration information, as changed in the application. For example, web.tap when shutdown will have an additional file, web-shutdown.tap.

Packaging

Twisted Applications can be packaged as DEBs? (tap2deb command) or RPMs? (tap2rpm command).

Reconfiguring

What are Twisted Services?

What are Twisted Reactors?

The Twisted Framework supports multiple communications protocols, only one of which is HTTP. Regardless of the set of protocol(s) involved, they are grouped into an "application" which is your single-process executable program, written in Python.

Twisted "applications" are instances of the twisted.application.service.Application class. Such an instance retains configuration information that persists between runs of the program. There is only a single such instance created per program and it acts as the root object of a tree of services implementing the IService.

Application objects

Applications are just Python objects, which can be created and manipulated in the same ways as any other object. In particular, they can be serialized to files. Twisted supports several serialization formats.

Instances of Twisted Application objects are created with the mktap command-line tool. The act of creating an Application object is the act of configuring it. Application objects can be created based on any of several existing Application classes (web, ftp, ...), or custom Application classes, of which mktap is made aware of through the Twisted plugin architecture.

twistd

Having an Application in a variety of formats, aesthetically pleasing as it may be, does not actually cause anything to happen. For that, we need a program which takes a dead Application and brings life to it. For UNIX systems (and, until there are are alternatives, for other operating systems too), this program is twistd(1). Strictly speaking, twistd is not necessary -- unserializing the application, getting the IService? component, calling startService, scheduling stopService when the reactor shuts down, and then calling reactor.run() could be done manually. twistd(1), however, supplies many options which are highly useful for program set up.

twistd supports choosing a reactor (for more on reactors, see Choosing a Reactor), logging to a logfile, daemonizing and more. twistd supports all Applications mentioned above -- and an additional one. Sometimes is is convenient to write the code for building a class in straight Python. One big source of such Python files is the doc/examples directory. When a straight Python file which defines an Application object called application is used, use the -y option.

When twistd runs, it records its process id in a twistd.pid file (this can be configured via a command line switch). In order to shutdown the twistd process, kill that pid (usually you would do kill `cat twisted.pid`). When the process is killed in an orderly fashion it will leave behind the shutdown Application which is named the same as the original file with a -shutdown added to its base name. This contains the new configuration information, as changed in the application. For example, web.tap when shutdown will have an additional file, web-shutdown.tap.