Galaxy Communicator Documentation:

Process Monitor Reference

License / Documentation home / Help and feedback

Command line

<GC_HOME>/contrib/MITRE/tools/bin/process_monitor <flags>
<GC_HOME>/contrib/MITRE/tools/bin/process_monitor <config_file> [<config_name_or_index>] [-- <arg>*]
<GC_HOME>/contrib/MITRE/tools/bin/csh_process_monitor <flags>

Both these tools manage the behavior of the Hub and multiple servers (although they can be used to manage any arbitrary executable). The process_monitor is a Python GUI which provides a pane for each managed executable; the panes can be hidden and redisplayed, and each process can be stopped and restarted. The csh_process_monitor is a version which provides a separate xterm for each process (so it does not provide some of the process management support). If <GC_HOME>/templates/config.make has not enabled Python at compilation time, process_monitor will be identical to csh_process_monitor.

There are two different ways of configuring the Python GUI: through command line flags or through a configuration file. You may use one or the other, but not both. For the csh tool, only the command line flag option is available.

You can also consult the process monitor tutorial.

What processes can be controlled?

The process monitor spawns a subprocess for each executable, and controls the process through the process ID of the process it spawns. What this means is that when the process monitor kills a subprocess, it can only kill the subprocess it spawned, not any of that process's children. This imposes some limitations and requirements on these subprocesses on the various platforms.

Unix

Each subprocess is passed as a command line to /bin/sh. This has an advantage and a disadvantage. The advantage is that you can invoke any command, including shell built-ins like printenv. The disadvantage is that any real executable is now a child of the spawned process. This is why, when you see the invoked subprocess in the process monitor display pane, the subprocess is prefixed with exec. This shell built-in substitutes the new process for the old in the current process space, so in effect, /bin/sh turns into the process you wanted to call.

This set of requirements imposes some restrictions on the command lines you can invoke. You can use shell redirection of I/O, but you shouldn't use pipes (separated by "|") or sequences (separated by ":"), even though you have a shell. The reason is that both of these constructs implicitly spawn a shell for each component, and even if you exec the entire line, you'll still end up killing the parent of what you really want to kill. Similarly, if your executable is a shell script, you must ensure that the shell script execs the executable it ultimately calls, or you'll once again end up killing the parent of what you really want to kill. (Note that this also imposes some restrictions on what sorts of shell scripts you can control.) So the following script is kosher:

#!/bin/sh exec /usr/bin/my_executable

but the following script is not:

#!/bin/sh /usr/bin/my_executable

Windows

On Windows, the command line you provide is the command line that gets invoked, because there's no such thing as exec among the MS-DOS batch commands. This means that the restrictions are a little different. First, if you want any MS-DOS built-ins, you have to prefix them with cmd.exe /c. Second, you shouldn't execute batch files at all as subprocesses, because the executables they invoke are guaranteed to be orphaned with the process monitor kills the batch shell that invoked them.

Command line flags

The relevant arguments for the two monitors differ slightly, but both processes will accept the entire set of arguments (and ignore the ones that aren't relevant). The command line arguments are "chunked"; there is a set of arguments for each process, for which the command line argument -c terminates each "chunk".

Argument	Applicable to Python	Appicable to csh	Description
`-T <string>`	yes	yes	The title of the particular process
`--open`	yes		Should the pane start open? (default is closed in Python, always open in csh)
`--start`	yes		Should the process be started automatically? (default is no in Python, always started in csh)
`--keep_alive`	yes		If specified, restart this process if it dies
`--input_line`	yes		Should a typein window be provided for this process? (default is no in Python, always available in csh)
`--input_return`	yes		Should a button be provided for inputting a carriage return? (default is no in Python, always available in csh)
`-c <string>`	yes	yes	The command line of the process. This command line should always be something that can be preceded with "exec".

In addition to these arguments there are five other, global arguments:

--ncols <int> (Python): how many columns should the process panes be arranged in? This argument can appear anywhere in the command line. Default is 1.
--compressed (Python): if specified, start up in a compressed configuration, with a single process viewer and buttons to switch the viewer between processes. When --compressed is specified, --ncols becomes the number of button rows. This argument can appear anywhere in the command line.
--clear_history <int> (Python): if specified, clears the history of each pane after the specified number of lines are written. This means that long-running processes won't grind to a halt because of Tcl update delays.
--master_title <title> (Python): if specified, sets the title of the main window (default is "Process monitor").
--sleep <int> (csh): how many seconds should the xterm sleep before starting the process? This argument can be interspersed anywhere in the command line, and applies to the current "chunk" and all subsequent chunks; this argument can be repeated. Initial default is 0.

In the Python version, the command line is echoed both in the history window and in a typein window. You can modify the command line in the typein window and the changes will be recognized on restart. Also, the "keepalive" behavior and the window configuration can be reconfigured after startup via the process monitor GUI.

Command line flag example

This example shows how you might use the process monitor in a C shell to start up a configuration of servers to interact with a database. Each of the command lines is a single line, in spite of the wrapping imposed by your browser.

% setenv MITRE_ROOT $GC_HOME/contrib/MITRE
% setenv DEMO_ROOT $MITRE_ROOT/examples/sql_explore
% $MITRE_ROOT/tools/bin/process_monitor --master_title "DB Interaction" \
    -T "DB" --open -c "$MITRE_ROOT/tools/bin/run_server $GC_HOME/contrib/MITRE/servers/bin/db_server -dblogin galaxy/galaxy" \
    -T "SQL Monitor" --open --input_line -c "$MITRE_ROOT/servers/bin/c_ui -prompt 'Type a query: ' -verbosity 0" \
    -T "Hub" --open -c "$GC_HOME/bin/hub -pgm_file $DEMO_ROOT/bare_query.pgm"

This invocation of the process monitor creates three panes, all of which are open at startup, all of which must be started by the user by hand.

The first is a database server, which is started by the run_server script.
The second is a typein server which has a space to type in a line.
The third is the Galaxy Communicator Hub executable.

Configuration file

All the information which can be specified on the command line can be specified in the configuration file, and more. A configuration file consists of a number of process blocks, as well as global information. Each of the process blocks may contain multiple processes, and each process block corresponds to a possible invocation of the process monitor. If there are multiple process blocks, and the name or index of the desired block has not been specified on the command line, the process monitor will list the available blocks and exit.

All arguments after a double dash ("--") on the command line are passed to the configuration file, to be substituted into the command lines in the same way that the EXPAND: directive does. These arguments are made available as $1, $2, etc., or as the name listed in the corresponding position in the ARGUMENTS: directive.

All entries in the configuration file are a single line long. Lines starting with a pound sign ("#") are ignored, as are lines consisting entirely of whitespace. The first token in the line is the directive, and the remaining data is the value. By convention, all the directives end with a colon (":").

Directive Value Scope Starts block Description

PROCESS: yes process yes The command line of the process. This command line should always be something that can be preceded with "exec". Identical to -c.

PROCESS_KEEP_ALIVE: no process no f specified, restart this process if it dies. Identical to --keep_alive.

PROCESS_TITLE: yes process no The title of the particular process. Identical to -T.

PROCESS_MONITOR_ARGS: yes process no Additional command line arguments to specify, such as --input_return, etc. These will be digested as they would in the corresponding set of arguments describing a process on the command line.

TITLE: yes process block yes The name of the process block. This name can be used as the second argument to the process monitor to specify one of a number of process blocks in a configuration file. Identical to --master_title.

EXPAND: yes global no A pair of tokens, the first being a string to be substituted, the second a string to substitute for. If there is no second token, the empty string is used as the substitution value. This can be used anywhere in the values for any subsequent entry, but are primarily intended to serve as shorthand in the command line. These expansions can also be chained; that is, subsequent EXPAND: entries can refer to previous EXPAND: entries. By convention, these expansions start with a dollar sign ("$"), to evoke the notion of environment variables.

There are three expansions which are set automatically by the process monitor:

$GC_HOME is set the root of the Galaxy Communicator installation.

$ARCHOS is set to the current ARCHOS value.

$OSTYPE is set to one of posix, dos, nt to indicate the "family" of the OS.

The process monitor also loads $GC_HOME/templates/$ARCHOS/config.values, which is generated automatically during the compilation process from the configuration settings for the distribution.

REQUIRES:
yes
process block
no
A sequence of tokens which will be checked against the expansions provided. Each token will be prefixed with a dollar sign ("$") and the result will be looked up in the expansions. If the token isn't found, the process block will be skipped. In this way, it's possible to skip process blocks if various expansions aren't defined (e.g., $JDK_HOME).

As a special case, if the token contains an equals sign ("="), the substring before the equals sign will be used as the lookup key, and the substring after the equals sign will be used as the required value of the expansion. So, for instance, an entry OSTYPE=posix in the REQUIRES: entry means that the process block will be executed only if the value of $OSTYPE is posix.

TEMPFILE:
yes
global
no
The value is a symbol which will be inserted into the list of expansions. The value of this expansion will be a distinguished temporary file. The scope of this temporary file is the process block. When the process block is started, a new filename is created, and when the block is terminated, the file, if it exists, will be deleted.

INCLUDE:
yes
global
no
The name of another file whose contents will be inserted at this point. You can use any substitutions in the value which have already been registered via EXPAND: at the point where this directive is read.

SUPPRESS_EXPANSIONS: no global no If present, the expansions specified in EXPAND: will only be applied when the command is actually executed; for display purposes, the unexpanded string will be used

NUM_DIVISIONS: yes global no How many columns should the process panes be arranged in? Identical to --ncols.

COMPRESSED: no global no if specified, start up in a compressed configuration, with a single process viewer and buttons to switch the viewer between processes. When COMPRESSED: is specified, NUM_DIVISIONS: becomes the number of button rows. This argument can appear anywhere in the command line. Identical to --compressed.

CLEAR_HISTORY: yes global no If specified, clears the history of each pane after the specified number of lines are written. This means that long-running processes won't grind to a halt because of Tcl update delays. Identical to --clear_history.

ARGUMENTS: yes global no If specified, provides a sequence of tokens which corresponds to the arguments expected after the double dash ("--"). No optional arguments are permitted. If not all arguments are present, the process monitor will fail. If there are extra arguments, they will be ignored. The resulting bound arguments can be referred to by name or position, with a prefixed dollar sign ($).

Configuration file example

The following configuration file does exactly the same thing as the command line flag example. Again, all directives are single lines, in spite of the wrapping in your browser:

EXPAND: $MITRE_ROOT $GC_HOME/contrib/MITRE
EXPAND: $DEMO_ROOT $MITRE_ROOT/examples/sql_explore
TITLE: DB Interaction
PROCESS: $MITRE_ROOT/tools/bin/run_server $MITRE_ROOT/servers/bin/db_server -dblogin galaxy/galaxy
PROCESS_TITLE: DB
PROCESS_MONITOR_ARGS: --open
PROCESS: $MITRE_ROOT/servers/bin/c_ui -prompt 'Type a query: ' -verbosity 0
PROCESS_TITLE: SQL Monitor
PROCESS_MONITOR_ARGS: --open --input_line
PROCESS: $GC_HOME/bin/hub -pgm_file $DEMO_ROOT/bare_query.pgm
PROCESS_MONITOR_ARGS: -T "Hub" --open