11.0 Executing remote programs

Legion's remote execution allows you to run remotely executed programs from the Legion command line, taking advantage of Legion's distributed resources. Your workload can be spread out on several processors, improving job turn-around time and performance. You can execute multiple instances of a single program or execute several different programs in parallel.

11.1 Introduction

A remote program is an executable process that can be started with a command-line utility. Note that a remote program is not part of the Legion system, but is an independent program that may or may not be linked to Legion. Remote programs might be shell scripts, compilers, existing executables, etc. The term "remote" here means that the program does not need to be executed on the local host.

11.2 Linked and independent programs

Legion can run both linked and independent programs. A Legion-linked program is linked to the Legion libraries. An independent program does not have these links.

Legion can run both Legion and non-Legion (i.e., programs that are not linked to the Legion libraries, such as shell scripts) remote programs since it relies on two different types of interfaces to pass Legion's execution order to the program. Before either a linked or independent remote program can be run from Legion it must be registered . The legion_register_runnable command registers Legion-linked programs, and the legion_register_program command registers an independent program. A single command, legion_run, runs both types of remote programs. Both of these commands have parameters that include the remote program's binary path name and architecture and assign the program a context path name: this allows Legion to know where the program's executable files are located, what platform the files use, and how to find the program's Legion interface.

11.3 Registering independent programs

Independent remote programs are registered with the legion_register_program command. This includes information about the program's architecture (e.g., linux, sgi, solaris, etc.), its binary path name, and a program class.

Usage is:

legion_register_program
    <program class>
    <Unix executable path>
    <legion arch> [-debug] [-help]

The <program class> parameter is a context path name for the class that will manage Legion objects related to a particular program. Note that since you decide how to organize your context space the path name can be whatever you find most convenient. You might want to use the name of the program in the <program class> parameter, so that it will be easier to remember (e.g., if I'm registering a program called "MyProgram" I will use MyProgram as the <program class> parameter). The context path name can be either new or a previously created path name (if you are registering multiple versions of the same program). It will refer to a (new or previously created) Legion object that functions as a proxy for executing an independent remote program.

If multiple programs are registered with the same program class and architecture, the most recently registered version will be used when the program is run on that particular architecture. Be sure to reregister the program if you recompile it, since Legion makes a copy of your executable for context space only when you register it.

The legion_register_program command creates a proxy object (an instance of the JobProxy class) to handle that particular program. Once the program has been registered, it can be executed with the legion_run command. The proxy object is then activated and can instruct the program to begin execution.

An example of this command might look like this:

$ legion_register_program myProgram /bin/myProgram linux
Program class "myProgram" does not exist.
Creating class "myProgram".
Registering implementation for class "myProgram"
$

This output shows Legion creating the program class myProgram, as the command requested. If this class had been previously created, the output would look like this:

$ legion_register_program myProgram /bin/myProgram linux
Registering implementation for class "myProgram"
$

11.4 Registering Legion-linked programs

The legion_register_runnable command registers programs that are linked to the Legion libraries, and exports a runnable object interface. The command creates an interface between the Legion system and the remote program and this interface transfers the execution command from Legion to the remote program. Like legion_register_program, this command specifies the remote program's program class, executable binary path, and architecture. Its usage is:

legion_register_runnable
    <program class> <executable path>
    <legion arch> [debug] [-help]

As with legion_register_program, the <program class> parameter is a context path name for the Legion objects that will handle a particular program. And, again, you are free to choose a context path that best suits your organizational scheme or use a previously created context (although you might want to use the name of the program in the <program class> parameter, so that it will be easier to remember). In that case, note that Legion will use the most recently registered program class and architecture when running a remote program. Once the program has been registered, it can be run with the legion_run command. Note that you must reregister the program if you recompile it (Legion copies your executable to context space when you register it).

$ legion_register_runnable myProgram /bin/myProgram linux
Program class "myProgram" does not exist.
Creating class "myProgram".
Registering implementation for class "myProgram"
$

This output shows Legion creating the program class myProgram, as the command requested. If this class had been previously created, the output would look like this:

$ legion_register_runnable myProgram /bin/myProgram linux
Registering implementation for class "myProgram"
$

11.5 Running a remote program

Use legion_run to remotely execute programs. Note that you must first register the program with either legion_register_program for independent programs or legion_register_runnable for Legion-linked programs. The usage of this command is:

legion_run [-w] [-v] [-a <architecture>]
    [-h <host context path name>]
    [-in <context path name>]
    [-out <context path name>]
    [-IN <local file name>]
    [-OUT <local file name>]
    [-f <options file>]
    <program class>
    [-t <minutes>] [-n <nodes>]
    [<arg1> <arg2> ... <argn>]
    [-debug] [-help]

The legion_run command executes a single instance of the program associated with the <program class> parameter. Legion will arbitrarily choose a host with a suitable architecture (specified when the program was registered) to execute the program. If you are running a serial program with many input files and/or multiple executions you may prefer to use the legion_run_multi command (see page 79 in the Reference Manual).

There are several optional parameters associated with legion_run. The -w flag directs the command's output to your tty object. The -v flag runs the command in verbose mode. Note that if you have not created and set a tty object for your current window, you will not be able to see the command's output and an error message will appear. Use the legion_tty command to create and set a tty object if you have not already done so (see page 65).

The -a flag allows you to specify the type of platform the program requires. Note that the possible architectures are limited. At the moment they are:

Architecture

Corresponds to

Comments

solaris

Sun workstations running Solaris 5.x

sgi

SGI workstations running IRIX 6.4

linux

x86 running Red Hat 5.x Linux

x86_freebsd

x86 running FreeBSD 3.0

alpha_linux

DEC Alphas running Red Hat 5.x Linux

alpha_DEC

DEC Alphas running OSF1 v4

rs6000

IBM RS/6000s running AIX 4.2.1

hppa_hpux

HPUX 11

winnt_x86

Windows NT 4.0

t90

Cray T90s running Unicos 10.x

virtual hosts only (see page 61 in the System Administrator Manual)

t3e

Cray T3E running Unicos/mk 2.x

virtual hosts only (see page 61 in the System Administrator Manual)

The -h flag allows you to specify which host should execute the program. The host must be part of your system (i.e., have a context name in your context space: if not use the legion_starthost command to add it).

The -in <context path name> option allows you to select a Legion file that should be copied into the remote program's current working directory before the program executes. The -out <context path name> option instructs Legion to copy the program's output from the remote program's current working directory to the Legion file named in <context path name>, after the program terminates (partial results will be available if the program crashes).

Two other options operate on a local file: -IN <local file name> tells Legion to copy the files named in <local file name> into the remote program's current working directory before the program executes, and -OUT <local file name> tells Legion to copy the program's output to the file named in <local file name>.

Files that are listed with the -in/-out and -IN/-OUT options can be named with either full or relative path names. Note, however, that the remote program will use the file path's basename (i.e., as relative path names from the current working directory) to gain access to the named file. New files will be given names corresponding to the basename of the current Legion context path or local directory path.

Depending on the program, you may need to request a block of time and/or number of nodes on the host: the -t flag specifies how many minutes the program needs and the -n flag specifies how many nodes. These options are pointless, of course, if the host selected to run the remote program does not enforce time limits for jobs, or is a uniprocessor or does not support multi-node allocations.

The <arg1> <arg2> ... <argn> parameter represents arbitrary command-line arguments.

If your program requires extensive use of these options you may want to use the -f flag, which allows user to list the options in a separate file rather than on the command line. The file can be delimited with spaces or new lines and can contain any of the options discussed above except for the program class name and any command-line arguments: those must appear on the command line.

11.6 Converting a C/C++ program

Any C or C++ program can be made into a Legion runnable object using the following steps:

  1. The program should export a C-linkable legion_main function in place of its main function.
  2. The program should be linked to the Legion libraries. Add the following to your link line:
-lLegionRun -lLegion1 -lLegion2

11.7 Summary

The entire process, using the Unix cp process as a sample program, might look something like this:

$ legion_register_program cp /bin/cp linux
Program class "cp" does not exist.
Creating class "cp".
Registering implementation for class "cp"
$ legion_run -in /dir1/src -out /dir2/dest cp src dest
$

The remote Unix program cp is first registered, and the program class cp is created in the user's local context, /bin/cp is declared to be its local executable path name, and linux is declared to be its architecture type.

The program is then remotely executed on a arbitrarily chosen linux host, and a series of events takes place: first, the -in option tells Legion to copy the Legion file /dir1/src into the remote program's cp's current working directory and call it src. The remote program cp then executes, copying src to a new Unix file, dest. Finally, once cp has terminated, Legion copies the contents of Unix file dest to a new Legion file called dest, and adds the context name dest to /dir2 (i.e., if the user runs legion_ls, dest will now be listed and will refer to the dest file).

Note that you can ask for multiple input and output files when you execute a program by repeating the -in/-out and -IN/-OUT options.

Directory of Legion 1.6.4 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source

legion@Virginia.edu
http://legion.virginia.edu/