Legion 1.2
Developer Manual

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:
    UVaL_Reference<LegionPackableString> password;
 public:
    UVaL_Reference<LegionImplicitParameterList> login 
    (UVaL_Reference<LegionPackableString> p);
    int set_password (UVaL_Reference<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::login() and AuthenticationObject:: set_password().

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:

and Legion message stack hooks:

Magic Name

Event

Priority

LegionMayI

MethodReceive

LegionMethodMayI_Prio+1.0

LegionLibraryInitialize

LibraryInitialize

1.0

LegionAcceptMethods

AcceptMethods

1.0

LegionObjectShutdown

ObjectShutdown

1.0

LegionSaveState

ObjectSaveState

1.0

LegionRestoreState

ObjectRestoreState

1.0

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 UVaL_PackableSet in your interface, you will have to edit the resulting files in order to call new on UVaL_PackableSet_LinkedList. 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

-N integer		Integer where method numbering should begin. Default is 200.
-C class_name		Class of resulting object. Defaults to nothing, which means it will inherit its class ID
							    from its class. But if the new class is a command line class object, you need to specify
     							    UVaL_CLASS_ID_COMMANDLINE.
-A			Generates code for an add-in trans file instead of a main transfile.
-o nomain		Comma-separated list of options. So far, there is only one option, nomain, which generates
     							    no main program. This option is intended for program with custom server loops.
-I include/path/	Path to the C include files.
-g			Print debugging messages at run-time for every method invocation.

Back to Languages sectional index

Back to Developer Manual Table of Contents