Module pluginlib

Overview

The pluginlib module provides the means for a KOS plugin service to hook itself up with the KOS. It also provides a utility function which simplifies the creation of connected child processes, to support multiple long-lived client-server connections.

Functions

register (plugin_name[, kernel_name ...]) -> (kosobj, nsobj)

Every plugin should start with a call to this function. The plugin_name argument gives the name of the plugin, which should be unique (no two plugins with the same name can exist in the same KOS). The kernel_name gives the name of the kernel with which the plugin should register; it defaults to the (short) name of the machine on which the plugin is executing. Note that a -n kernel_name (or --kernel kernel_name) command line option will always override the value given here, since the function parses the command line arguments itself, using sys.argv for the command line. When a command line parsing error is detected, the getopt.error exception is raised.

If the plugin uses additional command line options, it must pass the second and third arguments for the standard Python library function getopt.getopt() as the 3rd and 4th arguments to register(); the kernel_name argument may be set to None. (The register() function does not pass the results of parsing the command line back to its caller, but it is necessary to pass the getopt() arguments in order to prevent raising getopt.error.)

(XXX This is a pretty confusing state of affairs. If it is at all desirable that register() parses the command line, there should be a way to pass in sys.argv[], or there should be a way to prevent it from parsing.)

The function locates the specified kernel, and creates a context for the plugin in the kernel's plugins context (using the plugin_name argument as its name). It then calls the RegisterPlugin() method of the kernel's receiver, which registers the plugin with the receiver and returns a reference to the PluginEntry object created for the plugin.

The function returns a pair of values (kosobj, nsobj). The first, kosobj, provides an interface to access KOS kernel specific operations, and is documented in with the KOS bastion methods. The second, nsobj, is a new namespace context for private use by the plugin. It contains two predefined names: kos is the toplevel context of the KOS with which the plugin is registered; world is the worldroot context.

The register() function fails and terminates the process with an exit value of 1 if:

it is unable to find a local worldroot server
it is unable to find the designated kernel
the kernel lacks a plugins namespace
the kernel lacks a receiver

Note: This function finagles signal handling so that Control-C will kill the plugin. This is compensation for ILU's inherent inhibition of this behavior.

spawnserver (filename[, args[, flagoption]) -> (sbh, pid, pids)

This function simplifies the creation of connected child processes, to support multiple long-lived client-server connections. It takes the name of the file with the program to be forked, and returns the SBH for the new service, along with some information which the caller can use to manage the child processes.

The caller and child share a pipe. The file descriptor for writing on the pipe is passed as a command line argument to the child, which must use it to write its SBH, so spawnserver() can pass it to the caller. The file descriptor is, by default, preceded by a -f in the list of command line arguments, so the child can distinguish it from arbitrary other arguments.

If the fork succeeds but the exec in the child fails, the function will normally return a null string for the SBH.

filename (string): The name of a file containing the program to be forked.
args (sequence of strings): Command line arguments for the forked program; default an empty sequence.
flagoption (string): Flag to precede the file descriptor on which the child writes its SBH; default "-f".

Clarification: the following list of command line arguments is constructed for the program: [filename, flagoption, str(fd)] + list(args), where fd is the integer file descriptor for the write end of the pipe.

sbh (string): String Binding Handle of the child service
pid (integer): Process ID of the child
pids (list of integers): Process IDs of recently deceased child services

It is safe to ignore pid and pids; they are only needed if you wish to implement some form of subprocess management.