5.0 Object interface

Other than using a compiler that is Legion-aware (MPLC) or using a library that interfaces with Legion (MPI or PVM), the only way to interface objects with Legion is to write glue code by hand or to use the legion stub generator.

5.1 Stub generator

The Legion stub generator generates client-side and server-side stubs. The client-side stubs are linked to the developer's client code to build the client application. The server-side stubs are linked to the developer's implementation of the server-side functionality to build the Legion object.

The stub generator generates strict RPC method calls. Unlike MPLC, generate_stubs does no dataflow detection or complicated graph building.

For legacy purposes, generate_stubs functions in two modes: the default mode and the enhanced mode.

  1. Default Mode. In the default mode, generate_stubs takes a C++ header file as input. This mode supports only blocking methods and single return values.

    Example:

    Below is a C++ header file, which we are going to pass through generate_stubs:

    class HelloWorld { 
    public: 
    	HelloWorld();
    	int sayHello(); 
    };

    First, generate_stubs takes the header file as input and generates the following files:

    HelloWorld.client-stubs.new.c
    HelloWorld.client-stubs.new.h
    HelloWorld.trans.new.c
    HelloWorld.trans.new.h

    The first two files define a class called HelloWorld_client, which the developer will use in a client application to make method calls on the Legion HelloWorld object. So, to instantiate HelloWorld_client the developer would use:

    HelloWorld_client client(loid);

    To make a method call on the sayHello() method, he would use:

    int ret = client.sayHello();

    There are examples of this in the Legion source tree at $LEGION/SDK/src/Examples/StubGenerator.

    The two trans files, HelloWorld.trans.new.c and HelloWorld.trans.new.h, define a wrapper around the developer's implementation of the HelloWorld class, as defined in HelloWorld.h and HelloWorld.c. The developer need only link his implementation to the trans object code in order to build a Legion HelloWorld object capable of accepting and processing HelloWorld method calls.

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

    For examples of objects using the stub generator see $LEGION/SDK/src/Examples/StubGenerator. For examples of add-ins using the stub generator, see the AuthenticationObject and TrivialMayI objects.

  2. Enhanced Mode. The enhanced mode supports blocking and non-blocking methods and multiple return values. To use the enhanced mode, generate_stubs needs an IDL description of a class defined in a file with a .h.idl suffix as input. The Legion IDL is a C++ class description with several keywords: SYNC and ASYNC correspond to blocking and non-blocking method calls; IN, OUT, and INOUT refer to the direction of parameters.

    We can modify the default mode example:

    class HelloWorld {
    public: 
    	HelloWorld();
    	SYNC int sayHello(); 
    	ASYNC int sayHelloWithReturns(IN int, 
    		INOUT int, 
    		OUT LRef<LegionPackableString>); 
    };

    The above HelloWorld class description would be saved in a local file called HelloWorld.h.idl. This file would be passed as input to generate_stubs which would output the following files:

    HelloWorld.h // The HelloWorld class description with the
    // Legion IDL keywords stripped off
    HelloWorld.client-stubs.new.c
    HelloWorld.client-stubs.new.h
    HelloWorld.trans.new.c
    HelloWorld.trans.new.h

    There are examples of this in the Legion source tree at $LEGION/SDK/src/Examples/StubGenerator.

    These files are used in exactly the same way as they are for the default mode except that the HelloWorld client is defined slightly differently. If a method call is defined as SYNC, it will be defined exactly the same as in the default mode. If, however, a method call is defined as ASYNC, then the client definition of that method call will return an integer representing the id of that invocation of the method as well as methods for retrieving the return parameters of that method. For example, the definition of the sayHelloWithReturns() asynchronous method call described above would have the following client definition:

    int sayHelloWithReturns_async (int _legion_fnord_arg0,
    	int _legion_fnord_arg1,
    	struct timeval *timeout = NULL); 
    int get_sayHelloWithReturns_async_return ( int id,
    	struct timeval *timeout = NULL ); 
    void get_sayHelloWithReturns_async_param_1(int id, 
    	int _legion_fnord_arg1, 
    	struct timeval *timeout = NULL); 
    void get_sayHelloWithReturns_async_param_2(int id,
    	LRef <LegionPackableString> _legion_fnord_arg2,
    	struct timeval *timeout = NULL);

    The first function definition is the actual method call. The subsequent function definitions are the functions for retrieving the return parameters. The first argument for all retrieval methods is the invocation's id. The return from the actual method call must be passed to the retrieval methods in order to get the correct return parameters back.

    The developer is tasked with memory management of the invocations. The following functions are defined for memory management:

    void releaseInv(int id);
    void releaseAll();

    The first function will release memory only for the specified invocation. The second function will release all invocations.

Note: There are limits to the amount of C++ the stub generator can handle. 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 warnings. If the new class inherits from other Legion classes, the list of class names will begin 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.2 Options

-N <integer>

Integer where method numbering should begin. Default is 200.

-C <class_name>

Class of resulting object. Defaults to nothing, which means that 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 programs with custom server loops.

-I include/<path>/

Path to the C include files

-g

Print debugging messages at run-time for every method invocation

-S

Skip C preprocessor. This option is not recommended if the developer's code contains comments.

-v

Print startup message.

5.3 CORBA IDL compiler

The Legion-CORBA IDL is currently being reworked and is not yet available. Please contact <legion-help@virginia.edu> if you have any questions about using CORBA with Legion.

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

Free JavaScripts provided by The JavaScript Source

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