Controller

Extend the Controller class with your own application implementing the Controller.process method. If you do not want to use sleep based looping but rather an IOLoop or some other long-lived blocking loop, redefine the Controller.run method.

Controller maintains an internal state which is handy for ensuring the proper things are happening at the proper times. The following are the constants used for state transitions:

When extending Controller, if your class requires initialization or setup setups, extend the Controller.setup method.

If your application requires cleanup steps prior to stopping, extend the Controller.cleanup method.

class helper.Controller(args, operating_system)[source]

Extend this class to implement your core application controller. Key methods to implement are Controller.setup, Controller.process and Controller.cleanup.

If you do not want to use the sleep/wake structure but rather something like a blocking IOLoop, overwrite the Controller.run method.

APPNAME = 'sphinx-build'
SLEEP_UNIT = 0.5

When shutting down, how long should sleeping block the interpreter while waiting for the state to indicate the class is no longer active.

STATE_ACTIVE = 4

The active state should be set whenever the implementing class is performing a task that can not be interrupted.

STATE_IDLE = 3

The idle state is available to implementing classes to indicate that while they are not actively performing tasks, they are not sleeping. Objects in the idle state can be shutdown immediately.

STATE_INITIALIZING = 1

Initializing state is only set during initial object creation

STATE_SLEEPING = 2

When helper has set the signal timer and is paused, it will be in the sleeping state.

STATE_STOPPED = 7

Once the application has fully stopped, the state is set to stopped.

STATE_STOPPING = 6

Once the application has started to shutdown, it will set the state to stopping and then invoke the Controller.stopping() method.

STATE_STOP_REQUESTED = 5

The stop requested state is set when a signal is received indicating the process should stop. The app will invoke the Controller.stop() method which will wait for the process state to change from STATE_ACTIVE

VERSION = '2.4.2'
WAKE_INTERVAL = 60

How often should Controller.process() be invoked

cleanup()[source]

Override this method to cleanly shutdown the application.

configuration_reloaded()[source]

Override to provide any steps when the configuration is reloaded.

current_state

Property method that return the string description of the runtime state.

Return type:str
is_active

Property method that returns a bool specifying if the process is currently active.

Return type:bool
is_idle

Property method that returns a bool specifying if the process is currently idle.

Return type:bool
is_initializing

Property method that returns a bool specifying if the process is currently initializing.

Return type:bool
is_running

Property method that returns a bool specifying if the process is currently running. This will return true if the state is active, idle or initializing.

Return type:bool
is_sleeping

Property method that returns a bool specifying if the process is currently sleeping.

Return type:bool
is_stopped

Property method that returns a bool specifying if the process is stopped.

Return type:bool
is_stopping

Property method that returns a bool specifying if the process is stopping.

Return type:bool
is_waiting_to_stop

Property method that returns a bool specifying if the process is waiting for the current process to finish so it can stop.

Return type:bool
on_sighup(signum_unused, frame_unused)[source]

Called when SIGHUP is received, shutdown internal runtime state, reloads configuration and then calls Controller.run(). Can be extended to implement other behaviors.

on_sigterm(signum_unused, frame_unused)[source]

Called when SIGTERM is received, calling self.stop(). Override to implement a different behavior.

on_sigusr1(signum_unused, frame_unused)[source]

Called when SIGUSR1 is received, does not have any attached behavior. Override to implement a behavior for this signal.

on_sigusr2(signum_unused, frame_unused)[source]

Called when SIGUSR2 is received, does not have any attached behavior. Override to implement a behavior for this signal.

process()[source]

To be implemented by the extending class. Is called after every sleep interval in the main application loop.

run()[source]

The core method for starting the application. Will setup logging, toggle the runtime state flag, block on loop, then call shutdown.

Redefine this method if you intend to use an IO Loop or some other long running process.

set_state(state)[source]

Set the runtime state of the Controller. Use the internal constants to ensure proper state values:

  • Controller.STATE_INITIALIZING
  • Controller.STATE_ACTIVE
  • Controller.STATE_IDLE
  • Controller.STATE_SLEEPING
  • Controller.STATE_STOP_REQUESTED
  • Controller.STATE_STOPPING
  • Controller.STATE_STOPPED
Parameters:state (int) – The runtime state
Raises:ValueError
setup()[source]

Override to provide any required setup steps.

setup_signals()[source]
shutdown()[source]

Override to provide any required shutdown steps.

start()[source]

Important:

Do not extend this method, rather redefine Controller.run

stop()[source]

Override to implement shutdown steps.

system_platform

Return a tuple containing the operating system, python implementation (CPython, pypy, etc), and python version.

Return type:tuple(str, str, str)
wake_interval

Property method that returns the wake interval in seconds.

Return type:int