The CherryPy Engine¶
cherrypy.engine object contains and
manages site-wide behavior: daemonization, HTTP server start/stop, process
reload, signal handling, drop privileges, PID file management, logging for
all of these, and many more.
Any task that needs to happen outside of the request process is managed by the Engine via Plugins. You can add your own site-wide behaviors, too; see Custom Plugins. The Engine handles these tasks whether you start your site from a script, from an external server process like Apache, or via cherryd.
The Engine manages the state of the site. Engine methods like
cherrypy.engine.start move it
from one state to another:
O | V STOPPING --> STOPPED --> EXITING -> X A A | | \___ | | \ | | V V STARTED <-- STARTING
Note in particular that the Engine allows you to stop and restart it again without stopping the process. This can be used to build highly dynamic sites, and is invaluable for debugging live servers.
The Engine uses topic-based publish-subscribe messaging to manage event-driven
behaviors like autoreload and daemonization. When the Engine moves from one
state to another, it publishes a message on a channel named after the
activity. For example, when you call
cherrypy.engine.start, the Engine
moves from the STOPPED state to the STARTING state, publishes a message on
the “start” channel, and then moves to the STARTED state.
Engine Plugins package up channel listeners into easy-to-use components.
Engine Plugins have a
method which you can use to “turn them on”; that is, they will start listening
for messages published on event channels. For example, to turn on PID file
from cherrypy.process.plugins import PIDFile p = PIDFile(cherrypy.engine, "/var/run/myapp.pid") p.subscribe()
If you want to turn off a plugin, call
The following builtin plugins are subscribed by default: