Changeset 2634
- Timestamp:
- 02/23/10 21:04:35
- Files:
-
- trunk/sphinx/source/intro/concepts/dispatching.rst (modified) (1 diff)
- trunk/sphinx/source/intro/concepts/engineplugins.rst (modified) (2 diffs)
- trunk/sphinx/source/progguide/autoreloader.rst (modified) (2 diffs)
- trunk/sphinx/source/progguide/daemonizer.rst (modified) (2 diffs)
- trunk/sphinx/source/progguide/responsetimeouts.rst (moved) (moved from trunk/sphinx/source/progguide/monitor.rst) (1 diff)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/sphinx/source/intro/concepts/dispatching.rst
r2621 r2634 70 70 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 71 71 72 You can use dots in a URI like ``/path/to/my.html``, but Python method names don't allow dots. To work around this, the default dispatcher converts all dots in the URI to underscores before trying to find the page handler. In the example, therefore, you would name your page handler "def my_html". However, this means the page is also available at the URI ``/path/to/my_html``. If you need to protect the resource (e.g. with authentication), **you must protect both URLs**. 72 You can use dots in a URI like ``/path/to/my.html``, but Python method names 73 don't allow dots. To work around this, the default dispatcher converts all dots 74 in the URI to underscores before trying to find the page handler. In the 75 example, therefore, you would name your page handler "def my_html". However, 76 this means the page is also available at the URI ``/path/to/my_html``. 77 If you need to protect the resource (e.g. with authentication), **you must 78 protect both URLs**. 73 79 74 80 Other Dispatchers trunk/sphinx/source/intro/concepts/engineplugins.rst
r2631 r2634 1 .. _engineplugins:2 3 1 ************** 4 2 Engine Plugins 5 3 ************** 6 4 7 The ``cherrypy.engine`` object is a WebSiteProcessBus. To extend the behavior 8 of the bus, you subscribe ``plugins: engine.subscribe(channel, callback[, priority])``. 5 CherryPy allows you to extend startup, shutdown, and other behavior outside the 6 request process by defining *Plugins*. The ``cherrypy.engine`` object controls 7 these behaviors; to extend them, you subscribe plugins to the engine. Here's 8 the mechanism that gives you complete control over the subscription:: 9 10 engine.subscribe(channel, callback[, priority]) 11 9 12 The channel is an event name, like "start", "stop", "exit", "graceful", or 10 13 "log". The callback is a function, class, or other callable. The optional … … 12 15 13 16 Most of the built-in plugins have their own ``subscribe`` method, so that 14 instead of writing the above, you write: `` Plugin(engine).subscribe()``.15 That's it. If you want to turn off a plugin, call ``p lugin.unsubscribe()``.17 instead of writing the above, you write: ``p = Plugin(engine).subscribe()``. 18 That's it. If you want to turn off a plugin, call ``p.unsubscribe()``. 16 19 The plugin already knows the correct channel, callback, and priority. 17 20 18 21 Priorities of the built-in "start" listeners: 19 22 20 ====================== ================21 Listener Priority22 ====================== ================23 default 5024 : ref:`daemonizer`6525 : ref:`timeoutmonitor`7026 :ref:`autoreloader` 7027 :ref:`pidfile` 7028 :ref:`httpservers` 7529 :ref:`dropprivileges` 7730 ====================== ================23 ==================================================== ================ 24 Listener Priority 25 ==================================================== ================ 26 default 50 27 :doc:`Daemonizer </progguide/daemonizer>` 65 28 :doc:`TimeoutMonitor </progguide/responsetimeouts>` 70 29 :ref:`autoreloader` 70 30 :ref:`pidfile` 70 31 :ref:`httpservers` 75 32 :ref:`dropprivileges` 77 33 ==================================================== ================ 31 34 32 trunk/sphinx/source/progguide/autoreloader.rst
r2629 r2634 3 3 **************** 4 4 5 .. _autoreloader: 6 7 Autoreloader 8 ============ 9 10 The autoreload plugin restarts the process (via os.execv) if any of the files 11 it monitors change (or is deleted). By default, the autoreloader monitors all 12 imported modules; you can add to the set by adding to autoreloader.files:: 5 The autoreload :doc:`plugin </intro/concepts/engineplugins` restarts the process 6 (via :func:`os.execv`) if any of the files it monitors change (or is deleted). 7 By default, the autoreloader monitors all imported modules; you can add to the 8 set by adding to ``autoreloader.files``:: 13 9 14 10 cherrypy.engine.autoreload.files.add(myFile) … … 20 16 cherrypy.engine.autoreload.match = r'^(?!cherrypy).+' 21 17 22 Like all Monitor plugins (: ref:`monitor`), the autoreload plugin takes a18 Like all Monitor plugins (:doc:`monitor`), the autoreload plugin takes a 23 19 ``frequency`` argument. The default is 1 second; that is, the autoreloader 24 20 will examine files each second. trunk/sphinx/source/progguide/daemonizer.rst
r2631 r2634 3 3 *************** 4 4 5 .. _daemonizer: 5 CherryPy allows you to easily decouple the current process from the parent 6 environment, using the traditional double-fork:: 6 7 7 Daemonizer 8 ========== 8 from cherrypy.process.plugins import Daemonizer 9 d = Daemonizer(cherrypy.engine) 10 d.subscribe() 9 11 10 This component is used to decouple the current process from the parent environment, 11 using the traditional double-fork. It is only available on 12 Unix and similar systems which provide fork(). 12 .. note:: 13 14 This :doc:`plugin </intro/concepts/engineplugins>` is only available on 15 Unix and similar systems which provide fork(). 13 16 14 17 If a startup error occurs in the forked children, the return code from the … … 19 22 the process successfully finished the first fork. 20 23 21 The plugin takes optional arguments to redirect standard streams: stdin,22 stdout, and stderr. By default, these are all redirected to /dev/null, but 23 you're free to send them to log files or elsewhere.24 The plugin takes optional arguments to redirect standard streams: ``stdin``, 25 ``stdout``, and ``stderr``. By default, these are all redirected to 26 :file:`/dev/null`, but you're free to send them to log files or elsewhere. 24 27 25 **You should be careful to not start any threads before this plugin runs**. 26 The plugin will warn if you do so, because "...the effects of calling functions 27 that require certain resources between the call to fork() and the call to an 28 exec function are undefined". (`ref <http://www.opengroup.org/onlinepubs/000095399/functions/fork.html>`_). 29 It is for this reason that the Server plugin runs at priority 75 (it starts 30 worker threads), which is later than the default priority of 65 for the 31 Daemonizer. 28 .. warning:: 29 30 You should be careful to not start any threads before this plugin runs. 31 The plugin will warn if you do so, because "...the effects of calling functions 32 that require certain resources between the call to fork() and the call to an 33 exec function are undefined". (`ref <http://www.opengroup.org/onlinepubs/000095399/functions/fork.html>`_). 34 It is for this reason that the Server plugin runs at priority 75 (it starts 35 worker threads), which is later than the default priority of 65 for the 36 Daemonizer. 37 trunk/sphinx/source/progguide/responsetimeouts.rst
r2633 r2634 1 .. _monitor: 1 ***************** 2 Response Timeouts 3 ***************** 2 4 3 ************* 4 Timer threads 5 ************* 5 CherryPy responses include 3 attributes related to time: 6 6 7 Monitor 8 ======= 7 * ``response.time``: the :func:`time.time` at which the response began 8 * ``response.timeout``: the number of seconds to allow responses to run 9 * ``response.timed_out``: a boolean indicating whether the response has 10 timed out (default False). 9 11 10 A generic plugin to periodically run a callback in its own thread. Some of the 11 other builtin plugins subclass this already. 12 The request processing logic inspects the value of ``response.timed_out`` at 13 various stages; if it is ever True, then :class:`TimeoutError` is raised. 14 You are free to do the same within your own code. 12 15 13 * callback: the function to call at intervals. 14 * frequency: the time in seconds between callback runs. 16 Rather than calculate the difference by hand, you can call 17 ``response.check_timeout`` to set ``timed_out`` for you. 18 19 In addition, CherryPy includes a ``cherrypy.engine.timeout_monitor`` which 20 monitors all active requests in a separate thread; periodically, it calls 21 ``check_timeout`` on them all. It is subscribed by default. To turn it off:: 22 23 [global] 24 engine.timeout_monitor.on: False 25 26 or:: 27 28 cherrypy.engine.timeout_monitor.unsubscribe() 29 30 You can also change the interval (in seconds) at which the timeout monitor runs:: 31 32 [global] 33 engine.timeout_monitor.frequency: 60 * 60 34 35 The default is once per minute. The above example changes that to once per hour.
