rs - GUI tool for KP launching and control

Name

rs - GUI tool for KP launching and control

Synopsis

rs [-i] [-n name]

Description

The rs utility provides a graphical user interface to launch KPs and a variety of other capabilities needed to control KPs. Specifically, it allows KPs to be created and launched from Python source files, MIME files, or special template files which provide information about how a KP should be constructed. KPs are provided with an optional console window which shows the standard output and error streams for the KP. The user can kill a running KP. A composition tool is provided to edit complex KP specifications and template files.

There is a command line tool with approximately the same functionality, submit.

Command Line Options

The rs utility supports the following command line options. For each option, a short and a long form are supported. Long options start with two dashes.

-i

--iconic

Start up with the main window iconified (iconized, minimized, made into an icon).

-n name

--name name

Set the name of the utility in the namespace. This name is used to register this instance of the utility in the tools context of the KOE namespace. By default, rs will not register itself in the namespace. The registered object conforms to the MonitorAPI.MonitorServer interface.

User Interface

After initialization, the program will open the main application window, shown below after several KPs have run.

Figure 1. Main Window

The main window has a fairly typical organization, with global controls placed at the top, a status message area at the bottom, and an information display area in the middle. The middle information area is subdivided into two specific areas: the KP list and the details display. More controls are located below the display area to which they apply. The controls and display areas are discussed in more detail below.

Launching a KP

Clicking the Launch button on the main window displays a simple KP launching window, shown in Figure 2 below. The window allows the user to browse the local file system to locate files containing Knowbot Programs and either launch the KPs directly or load them into the KP Composer to allow editing of complex KPs.

Figure 2. Launcher Window

To directly launch a KP consisting of a single file, select the file in the list of filenames and click the Launch button. Double clicking the file has the same effect. The list of directory names makes it possible to browse the entire local file system. If the I/O Services checkbox is disabled, rs will not provide standard I/O channels for the KP. Use this feature only for KPs without output or whose output is not needed. The Keep launcher open checkbox can be enabled to support launching several of KPs without having to open the dialog each time. The Python, Template and MIME controls select the type of file to launch. The Filter button filters the list of filenames according to the pattern shown at the top of the window. The Cancel button closes the dialog without launching a KP. The Compose button loads the selected file in the KP Composer (see below).

The KSS which a KP is sent to can be controlled by a selection control in the lower portion of the window.

The List and Details Display Areas

The KP list area on the left shows a list of reporting IDs which have been assigned by this program. There are different ways to select which KPs are listed in this area; the options controlling the list will be discussed later. The Prune button and Current / Historic radio buttons are used to control this display, along with an additional control in the Options dialog. KPs in the list may be selected for detailed display in the details area by clicking on them with the mouse; double-clicking will cause a window containing KP output to be displayed if I/O services were requested when the KP was launched.

The details display on the right provides information about the current state of the KP selected in the KP list area. If no KP is selected, the fields in this area remain blank. This area provides information only; it does not provide control of running KPs. The information includes the current location (KSS name) of the KP (the location at which the KP terminated if it completed), the number of successful migrations, and the times the KP was launched, most recently migrated, and, if complete, when it terminated. Of great interest also is information on how the KP terminated: The Status field will be marked "Exit: return value" if the KP completed successfully, or "Exception: exception type" if the KP was terminated by an unhandled exception or KOS failure.

Controlling the KP List Area

The KP List Area on the left-hand side of the main window has two "modes," each with a pair on mutually exclusive options, and an operation for reducing the list which is used for three of the four mode / option combinations.

Each mode causes the list of KPs known to rs to be split into two groups; each KP will be in exactly one of the two groups. The mode determines how the split is made, and the option controls which of the two groups is displayed. These two variables are controlled by the options dialog (see below) and radio buttons under the list, respectively. Each of the modes and options are described below. Details of the Prune operation are described for each option.

Active / Completed

This mode distinguishes between KPs which are active, or running, and those which have completed either successfully or by an error.

Current / Historic

This is the default mode. In this mode, the lists reflect explicit pruning actions performed by the user.

Getting More Information on a KP

As might be expected from the presence of many labels and buttons on the right-hand side of the main window, a moderate amount of information about KPs submitted using rs can be made available. To see an overview of the information available for a single KP, use the KP List Area controls to locate the KP's entry in the list, then click on the entry to highlight it. The fields in the information area will be filled in for the selected KP and the buttons across the bottom of the information area will be enabled as appropriate.

The buttons in the information area are largely self-explanatory. The Kill KP button causes the KSS currently hosting the KP to send a SIGTERM to the process running the KP; ancestor and descendent KPs are not affected unless they expect the killed KP to continue operating. There is currently no way to kill multiple KPs (such as a KP and its clones) as a single operation. This button will only be enabled while the KP is running. The Show I/O... button will display the output window shared by the selected KP and any ancestor and descendent KPs. If the output window was not created or has been discarded, the button is disabled. A shortcut for this operation is to double click on the KP in the KP list area. The Traceback... button, active only if the KP exited abnormally and the hosting KOS was able to deliver traceback information, will cause a dialog containing the traceback information as delivered.

The Options Dialog

The Options... button pops up the (modeless) options dialog. The OK, Apply and Cancel buttons at the bottom control the dialog in the usual fashion.

Figure 3. Options Dialog

The List mode options were discussed in the previous section.

The KP/IO console options provide global control over the appearance of the console windows, providing default values for the per-window controls in each console window.

In the Miscellaneous options section, the Enable cloning option, when checked (as it is by default) allows the KPs managed by this instance of rs to create clones of themselves. The Publish client interface (also on by default) determines whether the MonitorAPI.MonitorServer interface discussed below is published in the tools context of the KOE namespace. This is also affected by the --name command line option.

Composing a KP

A sophisticated KP composition facility is available which can make writing large KPs a little simpler, and can ease repetitive launching of complex KPs significantly. Figure 4 below below shows the KP Composer with a KP consisting of a single module.

Figure 4. KP Composer Facility

The Composer can be opened from the main window or from the KP Launcher Window. When opened from the launcher, a KP will be loaded from a template file if one is selected or defined using a single module if a Python source file is selected. If a MIME file is selected, it will not be loaded and a warning dialog will be displayed.

Saving KPs

Knowbot programs can be stored from the Composer in two representations, each of which can retain all the information required to launch the KP from the Launcher Window at a future time. Of these two forms, only the template form can be used to load the built KP back into the Composer for further editing. The MIME format can be used to store a KP which can be launched from the any of the launch tools supplied with the KOE but which is not suitable for loading into the Composer.

KP template files are explained in KP Template File Format.

Tracking Knowbot Programs

Once a KP has been launched, rs can be used to track the KP's progress. Status information, including the location of the KP and the number of migrations it has completed, is made available at all times. In the main rs window, the information area on the right always displays the current status of the KP selected in the list of KPs on the left; see Figure 1 above. In addition to the right information area, the output of the KP's standard output and error streams is available if I/O Services option was selected in the KP Launch Window, or any of the standard I/O streams was set to "Window" in the Composer. If the KP terminates due to an exception, the exception information and traceback are available as well.

The standard output streams of the selected KP by pressing the Show I/O... button below the right information area. If there is no I/O display for the KP, the button will be disabled. Pressing the button brings up the KP Console window corresponding to the selected KP; a single Console is shared by a KP launched from rs and all of its descendents. A sample Console window is shown in Figure 5. When the KP has completed, the Console appears as in Figure 6.

Figure 5. KP Console Window

Figure 6. KP Console Window with no active KPs

The Console window supports some simple operations: the output buffer may be cleared, the window may be dismissed from the display, and automatic display may be requested based on output from the KP on either stream. When there are no more KPs running which have output on a console, a new button appears on the Console window labelled Discard and the control of output-initiated exposure is removed.

When a KP terminates, the reporting station responsible for monitoring its activity is notified and allowed to examine the state of the KP. If a KP terminates due to an exception other than SystemExit, rs stores the exception and traceback information. The exception type is displayed in the right information area of the main window when the KP is selected, and the traceback is made available via the Traceback... button. When the Traceback... button is pressed, a new window is created which shows the complete traceback, as shown in Figure 7.

Figure 7. Traceback Window

The MonitorAPI.MonitorServer Interface

The rs tool offers a remote interface which allows other tools to use the display and output services provided by the monitor. This feature has not yet been used in the base KOE distribution.

Bugs and Caveats

• The console window doesn't support interactive console input yet - use the command line submit tool for that.
• The traceback shown for a failed KP includes entries for the supervisor which started the KP. This can be confusing. (To fix it, the supervisor would have to be changed.)