The Circus package is composed of a high-level get_arbiter() function and many classes. In most cases, using the high-level function should be enough, as it creates everything that is needed for Circus to run.
You can subclass Circus’ classes if you need more granularity than what is offered by the configuration.
get_arbiter() is just a convenience on top of the various circus classes. It creates a arbiter (class Arbiter) instance with the provided options, which in turn runs a single Watcher with a single Process.
Creates a Arbiter and a single watcher in it.
Options:
watchers – a list of watchers. A watcher in that case is a dict containing:
name – the name of the watcher (default: None)
cmd – the command line used to run the Watcher.
args – the args for the command (list or string).
executable – When executable is given, the first item in the args sequence obtained from cmd is still treated by most programs as the command name, which can then be different from the actual executable name. It becomes the display name for the executing program in utilities such as ps.
numprocesses – the number of processes to spawn (default: 1).
warmup_delay – the delay in seconds between two spawns (default: 0)
shell – if True, the processes are run in the shell (default: False)
working_dir - the working dir for the processes (default: None)
uid – the user id used to run the processes (default: None)
gid – the group id used to run the processes (default: None)
env – the environment passed to the processes (default: None)
send_hup: if True, a process reload will be done by sending the SIGHUP signal. (default: False)
stdout_stream: a mapping containing the options for configuring the stdout stream. Default to None. When provided, may contain:
- class: the fully qualified name of the class to use for streaming. Defaults to circus.stream.FileStream
- refresh_time: the delay between two stream checks. Defaults to 0.3 seconds.
- any other key will be passed the class constructor.
stderr_stream: a mapping containing the options for configuring the stderr stream. Default to None. When provided, may contain:
- class: the fully qualified name of the class to use for streaming. Defaults to circus.stream.FileStream
- refresh_time: the delay between two stream checks. Defaults to 0.3 seconds.
- any other key will be passed the class constructor.
max_retry: the number of times we attempt to start a process, before we abandon and stop the whole watcher. (default: 5)
controller – the zmq entry point (default: ‘tcp://127.0.0.1:5555‘)
pubsub_endpoint – the zmq entry point for the pubsub (default: ‘tcp://127.0.0.1:5556‘)
stats_endpoint – the stats endpoint. If not provided, the circusd-stats process will not be launched. (default: None)
context – the zmq context (default: None)
background – If True, the arbiter is launched in a thread in the background (default: False)
stream_backend – the backend that will be used for the streaming process. Can be thread or gevent. When set to gevent you need to have gevent and gevent_zmq installed. (default: thread)
plugins – a list of plugins. Each item is a mapping with:
- use – Fully qualified name that points to the plugin class
- every other value is passed to the plugin in the config option
Example:
from circus import get_arbiter
arbiter = get_arbiter("myprogram", numprocesses=3)
try:
arbiter.start()
finally:
arbiter.stop()
Circus provides a series of classes you can use to implement your own process manager:
Wraps a process.
Options:
Return the pid
Return the stdout stream
Return the stdout stream
Sends a signal sig to the process.
Terminate the process.
Return the age of the process in seconds.
Return process info.
The info returned is a mapping with these keys:
Return a list of children pids.
Return True is the given pid is a child of that process.
Send signal signum to child pid.
Send signal signum to all children.
Return the process status as a constant
Example:
>>> from circus.process import Process
>>> process = Process('Top', 'top', shell=True)
>>> process.age()
3.0107998847961426
>>> process.info()
'Top: 6812 N/A tarek Zombie N/A N/A N/A N/A N/A'
>>> process.status
1
>>> process.stop()
>>> process.status
2
>>> process.info()
'No such process (stopped?)'
Class managing a list of processes for a given command.
Options:
name: name given to the watcher. Used to uniquely identify it.
cmd: the command to run. May contain $WID, which will be replaced by wid.
args: the arguments for the command to run. Can be a list or a string. If args is a string, it’s splitted using shlex.split(). Defaults to None.
numprocesses: Number of processes to run.
working_dir: the working directory to run the command in. If not provided, will default to the current working directory.
shell: if True, will run the command in the shell environment. False by default. warning: this is a security hazard.
uid: if given, is the user id or name the command should run with. The current uid is the default.
gid: if given, is the group id or name the command should run with. The current gid is the default.
send_hup: if True, a process reload will be done by sending the SIGHUP signal. Defaults to False.
env: a mapping containing the environment variables the command will run with. Optional.
rlimits: a mapping containing rlimit names and values that will be set before the command runs.
stdout_stream: a callable that will receive the stream of the process stdout. Defaults to None.
When provided, stdout_stream is a mapping containing two keys:
Each entry received by the callable is a mapping containing:
stderr_stream: a callable that will receive the stream of the process stderr. Defaults to None.
When provided, stdout_stream is a mapping containing two keys:
Each entry received by the callable is a mapping containing:
stream_backend – the backend that will be used for the streaming process. Can be thread or gevent. When set to gevent you need to have gevent and gevent_zmq installed. (default: thread)
priority – integer that defines a priority for the watcher. When the Arbiter do some operations on all watchers, it will sort them with this field, from the bigger number to the smallest. (default: 0)
singleton – If True, this watcher has a single process. (default:False)
options – extra options for the worker. All options found in the configuration file for instance, are passed in this mapping – this can be used by plugins for watcher-specific options.
send msg
Reap processes.
manage processes
Reap & manage processes.
Spawn processes.
Spawn process.
Kill process.
Kill processes.
Send signal to a child.
Stop.
Start.
Restart.
Class used to control a list of watchers.
Options:
watchers – a list of Watcher objects
endpoint – the controller ZMQ endpoint
pubsub_endpoint – the pubsub endpoint
stats_endpoint – the stats endpoint. If not provided, the circusd-stats process will not be launched.
check_delay – the delay between two controller points (default: 1 s)
prereload_fn – callable that will be executed on each reload (default: None)
context – if provided, the zmq context to reuse. (default: None)
to reuse. (default: None)
plugins – a list of plugins. Each item is a mapping with:
- use – Fully qualified name that points to the plugin class
- every other value is passed to the plugin in the config option
Starts all the watchers.
The start command is an infinite loop that waits for any command from a client and that watches all the processes and restarts them if needed.
Reloads everything.
Run the prereload_fn() callable if any, then gracefuly reload all watchers.
Return the number of processes running across all watchers.
Return the number of watchers.
Return the watcher name.
Adds a watcher.
Options: