habitat.main: the main method

The code in this module drives the “main” method

bin/habitat simply does the following:

import habitat
habitat.main.Program().main()

habitat.main.get_options()

get_options reads command line options and a configuration file

This function parses command line options, and reads a configuration file (which must be in the ConfigParser format).

It will read default_configuration_file and will ignore any errors that occur while doing so, unless a different config file is specified at the command line (failures on an explicitly stated config file will raise an execption).

Command line options have priority over options from a config file.

habitat.main.setup_logging(log_stderr_level, log_file_name, log_file_level)

setup_logging initalises the Python logging module.

It will initalise the ‘habitat’ logger and creates one, two, or no Handlers, depending on the values provided for log_file_level and log_stderr_level.

class habitat.main.Program

Program provides the main(), shutdown() and reload() methods

main()

The main method of habitat

This method does the following:

• calls get_options()
• calls setup_logging() with appropriate arguments
• creates the CouchDB connection object and tests for connectivity
• creates a habitat.message_server.Server
• creates a habitat.http.SCGIApplication
• creates a SignalListener
• starts the SCGI app thread
• starts the Program thread (see Program.run())
• starts the SignalListener thread

reload()

asks the Program thread to process a RELOAD event

shutdown()

asks the Program thread to process a SHUTDOWN event

run()

The Program thread processes SHUTDOWN and RELOAD events

In order to make shutdown() and reload() return instantly, the actual work requested by calling those methods is done by this thread.

• RELOAD: To be implemented
• SHUTDOWN: shuts down the SignalListener, habitat.http.SCGIApplication and the habitat.message_server.Server, then returns, killing this thread (Program.thread). Having shut down the above three, there should be only two threads executing: MainThread, which will be blocked in Program.thread.join(), and this thread. Therefore, immediately after this function returns, the process exits.

class habitat.main.SignalListener(program)

This class listens for signals

It responds to the following signals. When it receives one, it calls the appropriate method of Program

The documentation for the signal module contains information on the various signal constant definitions.

• SIGTERM, SIGINT: calls Program.shutdown()
• SIGHUP: calls Program.reload()
• SIGUSR1: exits the listen() loop by calling sys.exit() / raising SystemExit (NB: the listen() loop will be running in MainThread)

SIGUSR1 is meant for internal use only, and is used to terminate the signal-listening thread when the program wishes to shut down. (see SignalListener.exit())

setup()

setup() installs signal handlers for the signals that we want

Must be called in the MainThread

listen()

listen() listens for signals delivered to the process forever

It calls signal.pause() indefinitely, meaning that any signal sent to the process can be caught instantly and unobtrusivly.

Must be called in the MainThread

exit()

exit() terminates the listen() loop

It raises SIGUSR1 in this process, causing the infinite listen() loop to exit (SignalListener.handle() will call sys.exit())

handle(signum, stack)

handles a received signal