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.
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.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.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.
-
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.
ProcessProtocol
(deferred)[source]¶ Process protocol that manages short-lived processes
-
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