API

ncolony.service

Implement the ‘ncolony’ twistd plugin.

$ twistd ncolony --config <dir> --messages <dir>

Will run a service that brings up all processes described in files in the configuration directory (and shuts them down if the files ago away), and listens for restart messages on the messages directory.

class ncolony.service.Options[source]

Options for ncolony service

postOptions()[source]

Checks that required messages/config directories are present

class ncolony.service.TransportDirectoryDict(output)[source]

Dict-like object that writes the ‘pid’ value to a directory

This dict-like object assumes all the values have a ‘pid’ attribute, and writes that attribute into a file named the same as the key in the given directory.

ncolony.service.get(config, messages, freq, pidDir=None, reactor=None)[source]

Return a service which monitors processes based on directory contents

Construct and return a service that, when started, will run processes based on the contents of the ‘config’ directory, restarting them if file contents change and stopping them if the file is removed.

It also listens for restart and restart-all messages on the ‘messages’ directory.

Parameters:
  • config – string, location of configuration directory
  • messages – string, location of messages directory
  • freq – number, frequency to check for new messages and configuration updates
  • pidDir – {twisted.python.filepath.FilePath} or None, location to keep pid files
  • reactor – something implementing the interfaces {twisted.internet.interfaces.IReactorTime} and {twisted.internet.interfaces.IReactorProcess} and
Returns:

service, {twisted.application.interfaces.IService}

ncolony.service.makeService(opt)[source]

Return a service based on parsed command-line options

Parameters:opt – dict-like object. Relevant keys are config, messages, pid, frequency, threshold, killtime, minrestartdelay and maxrestartdelay
Returns:service, {twisted.application.interfaces.IService}

ncolony.ctllib

This module can be used either as a library from Python or as a commandline using the wrapper ctl via

$ python -m ncolony ctl <arguments>

Description of the service’s interface is in <figure out how to do a back-reference>.

The add/remove messages add/remove configuration files for processes. Since removal of a configuration is equivalent to killing the process, nothing else nees to be done to rid of needed processes.

All functions which are meant to be used as a library API

Add is the most complicated function, because it needs to be able to express every aspect of the process. It allows control of the name, command, arguments, environment variables and uid/gid.

Removal is pretty simple, since it only needs the name.

Restart also needs just the name.

Restart-all does not need even the name, since it restarts all processes.

class ncolony.ctllib.Places(config, messages)
config

Alias for field number 0

messages

Alias for field number 1

ncolony.ctllib.add(places, name, cmd, args, env=None, uid=None, gid=None, extras=None)[source]

Add a process.

Parameters:
  • places – a Places instance
  • name – string, the logical name of the process
  • cmd – string, executable
  • args – list of strings, command-line arguments
  • env – dictionary mapping strings to strings (will be environment in subprocess)
  • uid – integer, uid to run the new process as
  • gid – integer, gid to run the new process as
Returns:

None

ncolony.ctllib.call(results)[source]

Call results.func on the attributes of results

Params result:dictionary-like object
Returns:None
ncolony.ctllib.main(argv)[source]

command-line entry point

–messages: messages directory

—config: configuration directory

subcommands:
add:

name (positional)

–cmd (required) – executable

–arg – add an argument

–env – add an environment variable (VAR=value)

–uid – set uid

–gid – set gid

remove:
name (positional)
restart:
name (positional)
restart-all:
no arguments
ncolony.ctllib.remove(places, name)[source]

Remove a process

Params places:a Places instance
Params name:string, the logical name of the process
Returns:None
ncolony.ctllib.restart(places, name)[source]

Restart a process

Params places:a Places instance
Params name:string, the logical name of the process
Returns:None
ncolony.ctllib.restartAll(places)[source]

Restart all processes

Params places:a Places instance
Returns:None

ncolony.directory_monitor

Monitor directories for configuration and messages

ncolony.directory_monitor.checker(location, receiver)[source]

Construct a function that checks a directory for process configuration

The function checks for additions or removals of JSON process configuration files and calls the appropriate receiver methods.

Parameters:
  • location – string, the directory to monitor
  • receiver – IEventReceiver
Returns:

a function with no parameters

ncolony.directory_monitor.messages(location, receiver)[source]

Construct a function that checks a directory for messages

The function checks for new messages and calls the appropriate method on the receiver. Sent messages are deleted.

Parameters:
  • location – string, the directory to monitor
  • receiver – IEventReceiver
Returns:

a function with no parameters

ncolony.interfaces

Interface definitions

class ncolony.interfaces.IMonitorEventReceiver[source]
add()

New file appeared

Params name:string, file name
Params contents:
 string, file contents
Returns:None
remove()

File went away

Params name:string, file name
Returns:None
message()

Message sent

Params contents:
 string, message contents
Returns:None

ncolony.process_events

Convert events into process monitoring actions.

class ncolony.process_events.Receiver(monitor, environ=None)[source]

A wrapper around ProcessMonitor that responds to events

Params monitor:a ProcessMonitor
add(name, contents)[source]

Add a process

Params name:string, name of process
Params contents:
 string, contents parsed as JSON for process params
Returns:None
message(contents)[source]

Respond to a restart or a restart-all message

Params contents:
 string, contents of message parsed as JSON, and assumed to have a ‘type’ key, with value either ‘restart’ or ‘restart-all’. If the value is ‘restart’, another key (‘value’) should exist with a logical process name.
remove(name)[source]

Remove a process

Params name:string, name of process

ncolony.schedulelib

Construct a Twisted service for process scheduling.

$ twistd -n ncolonysched --timeout 2 --grace 1 --frequency 10 --arg /bin/echo --arg hello
class ncolony.schedulelib.Options[source]

Options for scheduler service

opt_arg(arg)[source]

Argument

class ncolony.schedulelib.ProcessProtocol(deferred)[source]

Process protocol that manages short-lived processes

childConnectionLost(reason)[source]

Ignore childConnectionLoss

childDataReceived(fd, data)[source]

Log data from process

Params fd:File descriptor data is coming from
Params data:The bytes the process returned
makeConnection(transport)[source]

Ignore makeConnection

processEnded(reason)[source]

Report process end to deferred

Params reason:a Failure
processExited(reason)[source]

Ignore processExited

ncolony.schedulelib.makeService(opts)[source]

Make scheduler service

Params opts:dict-like object. keys: frequency, args, timeout, grace
ncolony.schedulelib.runProcess(args, timeout, grace, reactor)[source]

Run a process, return a deferred that fires when it is done

Params args:Process arguments
Params timeout:Time before terminating process
Params grace:Time before killing process after terminating it
Params reactor:IReactorProcess and IReactorTime
Returns:deferred that fires with success when the process ends, or fails if there was a problem spawning/terminating the process