Support of Remote Program Execution


Table of Contents
Support of Remote Program Execution
Registering a non-Legion remote program
Registering a Legion remote program
     Converting a C/C++ Program to a Legion runnable object
Running a remote program

1.1 Support of Remote Program Execution

Typically, Legion objects must be linked with the Legion library in order to execute on hosts within the system and the library provides features needed by the system to control object execution. In many cases, though, users need to execute existing programs that cannot be relinked in the Legion system. Some programs simply cannot be linked with the Legion library (shell scripts, for example). Legion provides support for remotely executing non-Legion programs throughout the Legion system. Implementing this facility draws on the use of "proxy" Legion objects that act as intermediaries between running non-Legion programs and the Legion system.

Legion batch queuing commands can be used to remotely execute non-Legion programs throughout the Legion system. Remote programs may execute concurrently, providing a zero-effort opportunity for exploiting parallelism. For example, multiple sequential instances of a parameter-space study can be submitted for execution: they will execute in parallel, offering improved turn-around time with little added effort.

This service is based on three commands: two to register programs with the Legion system (legion_register_program for non-Legion programs and legion_register_runnable for Legion-linked programs), and one to start instances of a program executing (legion_run). Usage and explanations of these commands is provided below.

1.2 Registering a non-Legion remote program

The legion_register_program allows users to register a non-Legion executable program (specified by the <executable path> argument) and make the program available for use within the Legion system. Usage of this command is as follows.

    legion_register_program <program class> <executable path> <legion arch>
The registered program will be associated with a Legion class object. The class's context path is named in <program class>: the class and the context path will be created, if the class was not already created by a previous execution of legion_register_program. The registered program will execute only on hosts of the architecture specified in <legion arch>.

Any number of different architecture-specific versions of a program can be registered as belonging to a single program class. The different versions of a program associated with a single class are considered equivalent, although they may be registered with different architectures. In some cases, then, the same program might be registered for multiple architecture types: a single shell script might be registered for use on different Unix platforms, for example. If multiple programs are registered with the same class and the same architecture, the most recently registered version will be used for all executions on hosts of the architecture in question.

Programs registered through legion_register_program can be executed with the legion_run command (see below).

The following operands are used in this command:
<program class> The Legion context path name of the class with which
the registered program should be associated
<executable path> The local file path of the executable program to register.
This can be any program that could be run from the shell
command prompt, including scripts, and binary executable
generated by any programming language.
<legion arch> The platform type on which the program should be executed.

1.3 Registering a Legion remote program

The legion_register_runnable command is similar to the legion_register_program command in that it allows programs to be registered for execution through the legion_run utility. However, whereas the legion_register_program tool is used to register non-Legion programs, legion_register_runnable is used to register programs that are linked against the Legion libraries and export the "runnable" object interface. Usage of this command is as follows.
    legion_register_runnable <program class> <executable path> <legion arch>
The following operands are used in this command:
<program class> The Legion context space path of the class with which the registered program should be associated
<executable path> The local file path of the executable program to register. This program should be a valid Legion object implementation that has been linked with the Legion library, and that exports the Legion "runnable" interface.
<legion arch> The platform type on which the program should be executed.

1.3.1 Converting a C/C++ Program to a Legion runnable object

Note that any C or C++ program can be easily 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 with libLegionRun.a (in addition to the standard Legion libraries: libLegion.a and libBasicFiles.a).

1.4 Running a remote program

The legion_run command executes a single instance of a program associated with the program class specified in a <program class> argument. The command will randomly select a host to execute the program (observing the restriction that only hosts with an acceptable architecture may be selected). Support for directing scheduling (e.g. selecting a given host for remote execution) will be added in future releases. Arbitrary command-line arguments may be specified for the remote program. Usage of the command is below.

legion_run [-in <contex path name>] [-out <context path name>] 
	[-IN <local file name>] [-OUT <local file name>] 
	<program class> [<arg1>, <arg2>, ... <argn>]
Note that the remote program may be run on a host that does not have access to the local file system, since many legacy programs will not be able to use the Legion file system (which is intended to address the problem of disjoint file systems in metacomputing environments). To address this problem, legion_run provides a mechanism for copying files from the Legion file system or the local file system into the remote program's local working directory at the beginning of execution, and for copying files out of the remote program's local working directory into the Legion file system or the local file system on program termination. The -in and -out options allow the user to specify the files to be copied in to and out of the remote program execution, respectively. The -IN and -OUT options specify the paths of local (to legion_run's execution environment) files that should be copied into and out of the remote program execution. These options require that a <context path name> (for the -in/-out options) or <local file name> (for the -IN/-OUT options) be named. The remote program gains access to the named files by using the file path's base-name (i.e., all file operations performed by the remote program should be relative to the program's current working directory). This rule applies to both input and output files. For example:
    $ legion_register_program cp /bin/cp linux
    $ legion_run -in /dir1/src -out /dir2/dest cp src dest
The remote program cp is first registered, and /bin/cp is declared to be its local executable path name. The call to legion_run will result in the Legion file /dir1/src being copied into the remote cp process's current working directory under the under the name src. The execution of cp produces a file named dest in the program's current working directory. When the program is finished, this file is copied into a local files named dest in the user's home directory. This command is equivalent to (albeit much slower than):
    $ legion_cp /dir1/src /dir2/des 
Note that any number of input and output files may be specified for a single execution of legion_run (i.e., the -in/-out and -IN/-OUT options can be repeated).

The following operands are used in this command:
<program class> Specifies the program class of which an instance should be executed. This program class should have been created using the legion_register_program or legion_register_runnable command.
The following options are supported:
-in <context path name> Specifies the context path of a Legion file that should be copied into the remote program's current working directory before execution begins. The local file will have the same name as the <context path name> base-name.
-out <context path name> Specifies the context path of a Legion file that should be copied out of the remote program's current working directory after the program terminates. The local source file will have the same name as the <context path name> base-name. Note that output files are copied out regardless of the cause of program termination. Partial results will be available if the program crashes. Output files that are not found in the program's current working directory are skipped.
-IN <local file name> Similar to the -in option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>).
-OUT <local file name> Similar to the -out option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>).