5.0 Object interface

Other than using a complier that knows about Legion, such as MPLC (Mentat Programming Language Compiler), or a library that interfaces to Legion, such as MPI or PVM, the only way to interface objects to Legion is to write glue code by hand (how most of the system is done) or to use the stub generator.

The stub generator is a temporary utility which we hope to phase out as soon as MPLC's parser can be re-written. The stub generator generates both client-side and server-side stubs. Unlike MPLC, it does no dataflow detection or complicated graph building; all calls to other objects are strict RPC calls. On the server side, no monitor semantics are enforced, so whenever you call out you need to be able to deal with incoming methods.

The stub generator also allows you to build "add-in" objects, which are Legion software components. Add-in objects are compiled to .o files, which are then linked with some other object (which is unaware of the add-in). The add-in can manipulate the Legion message stack, as well as add functions to the interface. One example of an add-in object is TrivialMayI(), which both adds a MayI() security check to the message stack and extends the object's interface to allow methods that get and set security information.

Legion's IDL is currently expressed as a C++ header file. Here is a short example:

#include "legion/Legion.h"
class AuthenticationObject 
{
private:
 LRef<LegionPackableString> password;
public:
   LRef<LegionImplicitParameterList> login 
   (LRef<LegionPackableString> p);
   int set_password (LRef<LegionPackableString> newp);
};

The stub generator takes this input and outputs a client stub, which allows another Legion object to call these two methods, and a server stub ("trans file"), which accepts Legion method calls and turns them into calls on AuthenticationObject::set_password() and AuthenticationObject::login().

Any object (but especially an add-in object) uses special method names that either override object-mandatory functions such as SaveState or get hooked into the Legion message stack.

Special names that you can use include object mandatory functions:

• LegionMandatorySaveState
• LegionMandatoryRestoreState

and Legion message stack hooks (see Table 1).

Note that SaveState and RestoreState can be hooked to in two ways: add-ins get the event, but an object wants to get the method so that it can issue an appropriate reply.

For examples of objects and add-ins using the stub generator, see the AuthenticationObject and TrivialMayI objects, respectively.

There are limits to the amount of C++ which the stub generator can handle, however. If you have a type such as UPSet in your interface, you will have to edit the resulting files in order to call new on LPSetLL. The stub generator will generate memory leak warning. Give a name to every parameter in the interface, although I can almost always detect that it's missing and create one for you. If the new class inherits from other Legion classes include the list of class names, beginning with the parent and ending with the new class. Note that multiple inheritance is not supported. No client calls are generated for the object-mandatory interface.

5.1 Options

5.2 CORBA IDL compiler

The Legion-CORBA IDL is an OMG IDL compiler. It uses the legion_generate_idl command to parse CORBA input IDL files from a distributed application and generate Legion stub code for the application (Figure 13).

Figure 13: The Legion IDL

The stub code is currently written only in C++. The legion_make_idl command compiles the stub code with the client's and server's implementation code and generates an executable Legion client program and Legion server program.

The Legion IDL is an on-going project. It currently supports most IDL language features, such as modules, interfaces, operations, arguments, attributes, etc. It does not currently support the following features:

• enum
• sequence
• interface_fwd
• union
• any type parameter
• object parameters
• exceptions.

The Legion IDL is tested for a i386-linux platform, and the generated stub code is tested on i386-linux and Sun Solaris 2.5.1 platforms.

5.3 Using the Legion-CORBA IDL

The CORBA IDL files are located in the $LEGION/src/CORBA directory. You may need to compile these files separately. If so, move to the $LEGION/src/CORBA/OMG_IDL directory and type make. The executable legion_generate_idl program will be copied into your $LEGION/bin/$ARCH directory. Usage is as follows:

legion_generate_idl [<flags>]
<input file local path>

(Please see the Reference Manual or the man page for information about the legion_generate_idl flags.)

This command generates Legion stub files for input IDL files. Optional flags allow you to include information about the preprocessor and the back end and to specify whether or not trans code, client stubs, and header files should be created. If you run the command with no flags, Legion will generate client-side and server-side stubs. For example, if apps.idl is your input IDL file name and you run:

$ legion_generate_idl apps.idl

Legion will generate the following stubs files.

apps.client-stubs.new.h
apps.client-stubs.new.c
apps.mapping.h
apps.trans.new.h
apps.trans.new.c

On the other hand, if you run:

$ legion_generate_idl -client_stubs -header apps.idl

Legion will generate client-side stubs and header files but no .trans file.

apps.client-stubs.new.h
apps.client-stubs.new.c
apps.mapping.h

You must prepare the implementation code for the client and server. To build server code for the sample input file apps.idl, copy out the interface mapping from apps.mapping.h generated above to a new file called apps.org.h, derive a server class in apps.org.h from the base class generated in apps.mapping.h, then add private variables and methods to the server class.

The apps.client-stubs.new.h and apps.client-stubs.new.c should be compiled with an apps.client.c file, which must include code to implement the client part of the application. The implementation code of server code methods should be in a file called apps.org.c.

You can then use the legion_make_idl command to compile your stub files. Usage is:

legion_make_idl [-notrans] [-noclient]
[-v] [-noreg] [-s <suffix string>]
[-run] [-help] <application name>

(Please see the Reference Manual or the man page for information about the flags.) Continuing our example, if you ran:

$ legion_make_idl -v -s 1stTrial -run apps

the result will be:

apps_Client_1stTrial
apps_Class_1stTrial

And, assuming no compilation errors, the application will then run as:

$ apps_Client_1stTrial -c apps_Class_1stTrial

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