The submit utility is a command line tool to launch Knowbot Programs. By default, the standard I/O streams of the launched KPs and their clones are redirected to the I/O streams of the submit program, and submit waits until all launched KPs, including any clones that they may have spawned, have terminated. Options can modify this behavior.
Options generally have a long form (two dashes followed by a word) and a short form (a single dash followed by a letter).
Source file arguments are generally KP source files. By default, submit launches one KP for every comma-delimited list of source files, where a single filename is a list with one-element. Using the -1 argument, submit will launch a single KP consisting of all the files listed on the command line.
Any arguments appearing after a -- marker are passed on to the launched KP(s) as options and/or arguments.
Each non-option argument is either a MIME-encoded KP ("-" or a file ending in ".mime") or a comma-separated list of Python modules. If omitted or when an argument is "-", a single MIME-encoded KP is read from standard input.
If --single is given, a single KP is submitted and each argument specifies a module that becomes part of a list; thus, "submit --single a b c" is equivalent to "submit a,b,c". This may be handy if you rely on filename completion in your shell. In this case, '-' loses its special meaning and no MIME files can be submitted.
In order to pass command line options or arguments to the launched KP(s), specify them after a -- marker, after all the sources. These arguments are passed to each of the launched KPs. The KP can access them through inspection of sys.argv (sys.argv[0] is the KP name; the arguments are placed in sys.argv[1], sys.argv[2] and so on).
One or more --suitcase options control the contents of the suitcase sent along with the KP. The suitcase is only added to the first KP sent. The suitcase-spec values can have the following forms, where path is the pathname in the suitcase where the data is stored:
One or more --read-suitcase options direct the transfer of suitcase contents back to the filesystem upon completion of the first KP launched. The specification is similar to that for the --suitcase option but only the form path:file is supported. If path is found in the KP's suitcase, it is copied to file. Suitcase files not listed in --read-suitcase options, or suitcase files in other KPs than the first KP launched by this submit instance, or in clones of the first, are ignored.
Assume we have two test KP source files, test1.py and test2.py; test1.py can be run stand-alone; test2.py requires the modules mod1.py and mod2.py. We also have two data files test1.dat and test2.dat. Here are some example runs:
submit test1.py
submit test1
submit test1 -- -x
submit --suitcase input:test1.dat test1 -- input
submit --suitcase a:test1.dat --suitcase b:test2.dat test1
-- a b
submit --suitcase snow:="Melted snow" test1 -- snow
submit test1 test1
submit test2,mod1,mod2
submit --single test2 mod1 mod2
submit test1 test2,mod1,mod2
submit test1 test2 mod1 mod2
Normally, anything written by the KP(s) to sys.stdout, e.g., output of the print statement, or to sys.stderr will go to the standard output or error stream of submit. Likewise, if a KP reads from sys.stdin or uses the input() or raw_input() functions, a line will be read from submit's standard input.
Errors and warnings from submit and messages from its verbose mode (--verbose) will also go to its standard error stream. All these messages are preceded by the string "submit:" for easy filtering.
When the user hits the interrupt key (usually Control-C), submit takes the following actions.
The --verbose option prints various and sundry messages. It can be used to monitor a KP's migration and cloning patterns. It will also report the time elapsed for the submission and the execution. When repeated, it prints even more information. (Currently, this prints "Watchdog..." once a second to indicate that the internal "watchdog timer" is operational.)
The --monitor name option can be used to direct a KP's reporting events to another process. This feature has not yet been used in the base KOE distribution. It could be used to direct monitoring (but not I/O) of a KP to a running rs instance.
The --noioserver option can be used to avoid setting up an I/O server in the submit process. The KP's I/O will be directed to the console of the kernel where it is running, and will most likely be lost.
The --nogo option is useful to debug submit itself; it will go through all the motions of launching a KP except the actual launch. Best combined with --verbose.
The --showmime option is best combined with the --nogo option. This can be used to produce a MIME representation of the KP to be launched. The MIME representation is useful for inspection or for later launching from a filename ending in ".mime".
There is a GUI tool with roughly the same functionality, rs. See also killkp, a utility to kill runaway KPs.