manager Module

The manager module is a core component of gaffer. A Manager is responsible of maintaining processes and allows you to interract with them.


class gaffer.manager.Manager(loop=None)[source]

Bases: object

Manager - maintain process alive

A manager is responsible of maintaining process alive and manage actions on them:

  • increase/decrease the number of processes / process template
  • start/stop processes
  • add/remove process templates to manage

The design is pretty simple. The manager is running on the default event loop and listening on events. Events are sent when a process exit or from any method call. The control of a manager can be extended by adding apps on startup. For example gaffer provides an application allowing you to control processes via HTTP.

Running an application is done like this:

# initialize the application with the default loop
loop = pyuv.Loop.default_loop()
m = Manager(loop=loop)

# start the application

.... # do smth

m.stop() # stop the controlller # run the event loop


The loop can be omitted if the first thing you do is launching a manager. The run function is here for convenience. You can of course just run instead


The manager should be stopped the last one to prevent any lock in your application.

add_process(name, cmd, **kwargs)[source]

add a process to the manager. all process should be added using this function

  • name: name of the process
  • cmd: program command, string)
  • 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.
  • env: a mapping containing the environment variables the command will run with. Optional
  • uid: int or str, user id
  • gid: int or st, user group id,
  • cwd: working dir
  • detach: the process is launched but won’t be monitored and won’t exit when the manager is stopped.
  • shell: boolean, run the script in a shell. (UNIX only),
  • os_env: boolean, pass the os environment to the program
  • numprocesses: int the number of OS processes to launch for this description
  • flapping: a FlappingInfo instance or, if flapping detection should be used. flapping parameters are:
    • attempts: maximum number of attempts before we stop the process and set it to retry later
    • window: period in which we are testing the number of retry
    • retry_in: seconds, the time after we restart the process and try to spawn them
    • max_retry: maximum number of retry before we give up and stop the process.
  • redirect_output: list of io to redict (max 2) this is a list of custom labels to use for the redirection. Ex: [“a”, “b”] will redirect stdout & stderr and stdout events will be labeled “a”
  • redirect_input: Boolean (False is the default). Set it if you want to be able to write to stdin.
  • graceful_timeout: graceful time before we send a SIGKILL to the process (which definitely kill it). By default 30s. This is a time we let to a process to exit cleanly.

return list of named process of this group


return the groups list


generate a process id


get process info


return process stats for a process template or a process id


return the process status:

  "active":  str,
  "running": int,
  "max_processes": int
  • active can be active or stopped
  • running: the number of actually running OS processes using this template.
  • max_processes: The maximum number of processes that should run. It is is normally the same than the runnin value.
monitor(name_or_id, listener)[source]

get stats changes on a process template or id

on(evtype, listener)

subscribe to the manager event eventype

‘on’ is an alias to this function

once(evtype, listener)

subscribe to the manager event eventype

‘on’ is an alias to this function


iterator returning all processes stats


remove a group and all its processes. All processes are stopped


remove the process and its config from the manager


restart all processes in the manager. This function is threadsafe


restart all processes in a group


restart a process


Convenience function to use in place of If the manager is not started it raises a RuntimeError.

Note: if you want to use separately the default loop for this thread then just use the start function and run the loop somewhere else.


return running processes

send_signal(name_or_id, signum)[source]

send a signal to a process or all processes contained in a state


start the manager.


start all process templates of the group


start all processes


stop the manager. This function is threadsafe


stop all processes templates of the group


stop a process by name or id

If a name is given all processes associated to this name will be removed and the process is marked at stopped. If the internal process id is givien, only the process with this id will be stopped


stop all processes in the manager

subscribe(evtype, listener)[source]

subscribe to the manager event eventype

‘on’ is an alias to this function

subscribe_once(evtype, listener)[source]

subscribe once to the manager event eventype

‘once’ is an alias to this function

ttin(name, i=1)[source]

increase the number of system processes for a state. Change is handled once the event loop is idling

ttou(name, i=1)[source]

decrease the number of system processes for a state. Change is handled once the event loop is idling

unmonitor(name_or_id, listener)[source]

get stats changes on a process template or id

unsubscribe(evtype, listener)[source]

unsubscribe from the event eventype

update_process(name, cmd, **kwargs)[source]

update a process information.

When a process is updated, all current processes are stopped then the state is updated and new processes with new info are started


Table Of Contents

Previous topic

Core gaffer framework

Next topic

process Module

This Page