Handling Signals


This Engine Plugin is instantiated automatically as cherrypy.engine.signal_handler. However, it is only subscribed automatically by cherrypy.quickstart(). So if you want signal handling and you’re calling:

tree.mount(); engine.start(); engine.block()

on your own, be sure to add:

if hasattr(cherrypy.engine, 'signal_handler'):
class cherrypy.process.plugins.SignalHandler(bus)

Register bus channels (and listeners) for system signals.

You can modify what signals your application listens for, and what it does when it receives signals, by modifying SignalHandler.handlers, a dict of {signal name: callback} pairs. The default set is:

handlers = {'SIGTERM': self.bus.exit,
            'SIGHUP': self.handle_SIGHUP,
            'SIGUSR1': self.bus.graceful,

The SignalHandler.handle_SIGHUP`() method calls bus.restart() if the process is daemonized, but bus.exit() if the process is attached to a TTY. This is because Unix window managers tend to send SIGHUP to terminal windows when the user closes them.

Feel free to add signals which are not available on every platform. The SignalHandler will ignore errors raised from attempting to register handlers for unknown signals.


Restart if daemonized, else exit.

handlers = {}

A map from signal names (e.g. ‘SIGTERM’) to handlers (e.g. bus.exit).

set_handler(signal, listener=None)

Subscribe a handler for the given signal (number or name).

If the optional ‘listener’ argument is provided, it will be subscribed as a listener for the given signal’s channel.

If the given signal name or number is not available on the current platform, ValueError is raised.

signals = {1: 'SIGHUP', 2: 'SIGINT', 3: 'SIGQUIT', 4: 'SIGILL', 5: 'SIGTRAP', 6: 'SIGABRT', 7: 'SIGBUS', 8: 'SIGFPE', 9: 'SIGKILL', 10: 'SIGUSR1', 11: 'SIGSEGV', 12: 'SIGUSR2', 13: 'SIGPIPE', 14: 'SIGALRM', 15: 'SIGTERM', 17: 'SIGCLD', 18: 'SIGCONT', 19: 'SIGSTOP', 20: 'SIGTSTP', 21: 'SIGTTIN', 22: 'SIGTTOU', 23: 'SIGURG', 24: 'SIGXCPU', 25: 'SIGXFSZ', 26: 'SIGVTALRM', 27: 'SIGPROF', 28: 'SIGWINCH', 29: 'SIGPOLL', 30: 'SIGPWR', 31: 'SIGSYS', 34: 'SIGRTMIN', 64: 'SIGRTMAX'}

A map from signal numbers to names.


Subscribe self.handlers to signals.


Unsubscribe self.handlers from signals.

Windows Console Events

Microsoft Windows uses console events to communicate some signals, like Ctrl-C. When deploying CherryPy on Windows platforms, you should obtain the Python for Windows Extensions; once you have them installed, CherryPy will handle Ctrl-C and other console events (CTRL_C_EVENT, CTRL_LOGOFF_EVENT, CTRL_BREAK_EVENT, CTRL_SHUTDOWN_EVENT, and CTRL_CLOSE_EVENT) automatically, shutting down the bus in preparation for process exit.