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.
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:
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.
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.
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.
It is safe to ignore pid and pids; they are only needed if you wish to implement some form of subprocess management.