1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
*******************
The CherryPy Engine
*******************
The :class:`cherrypy.engine<cherrypy.process.wspbus.Bus>` 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 :doc:`/progguide/extending/customplugins`. The Engine
handles these tasks whether you start your site from a script, from an external
server process like Apache, or via :doc:`cherryd</deployguide/cherryd>`.
State Management
================
The Engine manages the *state* of the site. Engine methods like
:func:`cherrypy.engine.start<cherrypy.process.wspbus.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.
.. _channels:
Channels
========
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
:func:`cherrypy.engine.start<cherrypy.process.wspbus.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.
.. _plugins:
Plugins
=======
Engine Plugins package up channel listeners into easy-to-use components.
Engine Plugins have a :func:`subscribe<cherrypy.process.plugins.SimplePlugin.subscribe>`
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
management::
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 ``p.unsubscribe()``.
The following builtin plugins are subscribed by default:
* :doc:`Timeout Monitor</progguide/responsetimeouts>`
* :class:`Autoreloader<cherrypy.process.plugins.Autoreloader>` (off in the "production" :ref:`environment<environments>`)
* :class:`cherrypy.server<cherrypy._cpserver.Server>`
* :class:`cherrypy.checker<cherrypy._cpchecker.Checker>`
* Engine log messages go to :class:`cherrypy.log<cherrypy._GlobalLogManager>`.
* A :class:`Signal Handler<cherrypy.process.plugins.SignalHandler>`.
|
