[an error occurred while processing this directive]

5.0 Interfaces

Below we provide selected parts of the interface from selected objects that make up the Legion Library implementation.

5.1 Legion ProgramGraph

UVaL_Reference<LegionInvocation> add_invocation ()

Parameters: UVaL_Reference<LegionInvocation>

Add an invocation to the program graph. Returns the invocation if successful, NULL if not.

ParameterStatus add_constant_parameter()

Parameters: UVaL_Reference<LegionInvocation> target

UVaL_Reference<LegionParameter> parameter

int parameter_number

Adds the given parameter to the specified invocation as the `parameter_number 'th parameter. The parameter is a LegionParameter , which means that it contains an already computed value. The other possible is that it is an invocation parameter. This means that the parameter itself is a LegionInvocation , thus representing a computation that has yet to be performed.

ParameterStatus add_invocation_parameter()

Parameters: UVaL_Reference<LegionInvocation> source

UVaL_Reference<LegionInvocation> target

int source_parameter_number

int target_parameter_number

Adds the given source parameter as a parameter to the given target parameter. This call creates what is called a LegionContinuation , and adds the continuation to the continuation list for the source parameter. When an invocation request is eventually executed, the invokee must know where to send the results of the execution. Each LegionContinuation identifies a destination LOID to which a result should be sent.

void add_result_dependency()

Parameters: UVaL_Reference<LegionInvocation> source

int parameter_number

The current implementation always sends the return value of a method request back to the invoker. If the invoker wishes to receive other result values that e.g. might correspond to in/out parameters to the method invocation, then those values must be explicitly asked for using add_result_dependency . This call then creates a LegionContinuation corresponding to the requested parameter.

UVaL_Reference<LegionBuffer> get_value();

Parameters: UVaL_Reference<LegionInvocation> inv

int parameter_number

Gets the specified return value for the given LegionInvocation out of the program graph. This is essentially a call through the program graph to the underlying message database. If the result is not available, get_value blocks until it is. A LegionBuffer is returned.

int execute();

Parameters: None

Takes the program graph rooted at the provided invocation and fire it off to be executed. Does not block.

5.2 Legion InvocationStore

int enable_function ();

Parameters: int func_num

int priority

Enables the supplied function so that the LIS will accept method requests for it. Method requests for disabled functions are not accepted. High values for priority mean high priority.

int any_ready();

Parameters: None

Check to see if any method requests are ready.

int any_ready_for_func()

Parameters: int func_num;

Check to see if any method requests for the given function are ready.

UVaL_Reference<LegionWorkUnit> next_matched();

Parameters: None

Returns the next work unit. The priority scheme is obeyed.

UVaL_Reference<LegionWorkUnit> next_matched_for_func()

Parameters: int func_num;

Return the next work unit with the given function number.

int set_priority ();

Parameters: int func_num

int priority

Set the priority for the given function number.

int insert();

Parameters: UVaL_Reference<LegionWorkUnit> new_work_unit

Insert the provided work unit into the invocation store. This work unit may be a method request or it may be a result from a previous method invocation.

UVaL_Reference<LegionWorkUnit> get_return_value();

Parameters: UVaL_Reference<LegionComputationTag> tag

int parameter_number

Returns the work unit with the given tag and parameter number. Typically, this function is called by a higher layer (e.g. LegionProgramGraph ) which will unwrap the returned work unit to get the parameter inside.

int release_return_value();

Parameters: UVaL_Reference<LegionComputationTag> tag

int parameter_number

Deletes the work unit that matches the supplied tag/ parameter_number pair.

int release_all_return_values();

Parameters: None

Deletes all return values from the invocation store.

5.3 LegionWorkUnit

int get_function_number();

Parameters: None

Returns the target function number for the work unit.

UVaL_Reference<LegionContinuationList> get_continuation_list();

Parameters: None

Return the continuation list for the results of this work unit.

UVaL_Reference<LegionBuffer> get_parameter();

Parameters: int parameter_number;

Returns the given parameter as a LegionBuffer . NULL if the parameter is not in the work unit.

5.4 Legion Buffer

5.4.1 Constructors

LegionBuffer()

Parameters: None

The default constructor is for the common case; it creates an empty buffer with a LegionStorageScat storage, and default implementations of the packer, compressor, and encryptor function sets.

LegionBuffer()

Parameters: UVaL_Reference<LegionStorage>

The simple constructor wraps a default buffer around a given storage object. It uses default implementations for the packer, encryptor, and compressor.

LegionBuffer()

Parameters: LegionMetaData metadata

The meta-data based constructor creates a new empty LegionBuffer with a LegionStorageScat default storage implementation. It instantiates packer, encryptor and compressors based on the meta-data.

LegionBuffer()

Parameters: UVaL_Reference<LegionStorage>

LegionMetaData metadata

The full featured constructor wraps a specified storage in a buffer appropriate for the given meta-data, selecting the right packer meta-data, compressor, and encryptor implementations.

5.4.2 Operations on the associated LegionStorage

A LegionStorage exports member functions to read and write untyped characters from and to a logical buffer. These operations are also exported by LegionBuffer , but the user should be warned that the "better" way to put data into a buffer is through the LegionPacker interface; read() and write() will not perform appropriate data format conversions, but put_int() and get_int() will.

size_t read()

Parameters: size_t num_bytes

void *data

Reads num_bytes bytes from the buffer starting at the current location of the buffer pointer. Copies the bytes into the space pointed to by data_dest . Returns the number of bytes actually read, and positions the buffer pointer immediately after the last byte that was read. Read() will not read past the end of the buffer.

size_t write()

Parameters: size_t num_bytes

void *data

Writes num_bytes bytes pointed to by data into the buffer starting at current position of the buffer pointer (overwriting existing data). Returns the number of bytes actually written, and positions the buffer pointer immediately after the last byte that was written. Writing past the end of the buffer causes it to expand.

size_t seek()

Parameters: seek_start whence

int bytes_away

Changes the position of the buffer pointer. The whence parameter can be BEGINNING (0) , CURRENT (1) , or END (2) , and bytes_away tells how many bytes away from whence to set the pointer. Seeking past the end of the buffer causes it to expand and to be filled with NULL bytes. Seeking to negative logical positions the buffer does not cause the buffer to expand; the buffer pointer is placed at logical position 0 .

size_t size()

Parameters: None

Returns the current size of the buffer in bytes.

size_t current_byte()

Parameters: None

Returns the number of the byte to which the buffer pointer currently points. Current_byte() returns 0 when the buffer pointer is at the beginning of the buffer, and current_byte() == size() when the buffer pointer is at the end of the buffer.

char * linearize()

Parameters: int pack_metadata=0

Returns a pointer to the beginning of the buffer's data. This pointer is guaranteed to point to data that is contiguous in memory. Depending on the implementation of the LegionStorage , this function may or may not need to return a pointer to a copy of the data.

void setMetaData()

Parameters: LegionMetaData md

Sets the metadata associated with the LegionStorage .

LegionMetaData getMetaData()

Parameters: None

Returns the meta data associated with the LegionStorage . This is useful for instantiating an appropriate LegionBuffer based on a given LegionStorage .

5.4.3 Operations on the associated Legion Packer

A LegionPacker exports operations for packing and unpacking the basic C++ data types into and out of a LegionBuffer in a particular data format. A LegionPacker exports put_ZZZ() and get_ZZZ() for all ZZZ in {char, short, ushort, int, long, ulong, float, double} .

size_t put_ZZZ()

Parameters: ZZZ *source

int how_many

Assumes that source points to an array of how_many instances of type ZZZ . Copies this data into the buffer after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker that is instantiated.

size_t get_ZZZ()

Parameters: ZZZ *source

int how_many

Assumes that source points to enough space for an array of how_many instances of type ZZZ . Copies the next data from the LegionBuffer into this space after first performing the appropriate data conversion operation if necessary and appropriate for the type of LegionPacker that is instantiated.

5.4.4 Operations on the associated LegionEncryptor

Since no encryption algorithms have been implemented, the current encryption operations, encrypt() and decode() , are merely placeholders until the right set of encryption operations are defined.

5.4.5 Operations on the associated LegionCompressor

Since no compression algorithms have been implemented, the current compression operations, compress() and decompress() , are merely placeholders until the right set of compression operations are defined.

5.4.6 Legion Packable

int pack()

Parameters: int unpack()

LegionBuffer &lb

LegionBuffers are themselves packable.

5.4.7 Other functions

show()

Parameters: None

Prints the contents of the LegionBuffer to stderr . This is done however the associated LegionStorage sees fit.

5.4.8 Naming and binding: LegionLOID

LegionLOID is intended to be a base class for LOID's that enforce a particular structure on the fields of the LOID. An LOID contains four private data members, (1) an integer that holds the type of LOID, (2) an integer that indicates how many fields the LOID contains, (3) an array field_size[] of integers that holds the sizes in bytes of the LOID fields, and (4) an array field_value[] of pointers to the field data. Currently, the only derived class is called LegionGeneralPurposeLOID , which simply exposes the protected members to the public interface.

LegionLOID() (protected)

Parameters: int ltype

Sets the type to ltype , sets all other fields to zero.

LegionLOID() (protected)

Parameters: int ltype,

short nfields

Sets the type to ltype . Sets num_fields to nfields . Allocates the field_size[] and field_value[] arrays. Sets all field_size[] 's to 0 , sets all field_value[] 's to NULL .

LegionLOID() (protected)

Parameters: int ltype,

short nfields,

short *fld_size

Sets the type to ltype . Sets num_fields to nfields . Allocates the field_size[] and field_value[] arrays. Sets all field_size[] 's to the values contained in the fld_size[] array. Allocates the field_value[] entries to the right size and zeros them out. This constructor assumes the fld_size array has at least nfields elements.

LegionLOID() (protected)

Parameters: int ltype

short nfields

short *fld_size

char **fld_value

Sets the type to ltype . Sets num_fields to nfields . Allocates the field_size[] and field_value[] arrays. Sets all field_size[] 's to the values contained in the fld_size[] array. Allocates the field_value[] entries to the right size and copies the values from fld_value[] array into the field_value[] array. This constructor assumes that the fld_size[] and fld_value[] arrays have at least nfields elements, and that each fld_value[i] points to at least fld_size[i] bytes of space.

set_field_size() (protected)

Parameters: short field_num

short fsize

Sets the appropriate field_size element to fsize and makes sure that the corresponding field_value element is at least fsize bytes. If it is not, it deletes the old field_value entry and allocates a new one. Only derived classes should be allowed to call this member.

set_type() (protected)

Parameters: int new_type

Sets the type entry to be new_type . Can only be called from within the code of derived classes.

LegionLOID()

Parameters: LegionBuffer &lb

LegionLOID()

Parameters: LegionLOID &otherLOID

These two constructors are public because neither allows the caller to violate the structure of any particular type of LOID -- both just copy the LOID from the parameter, either a LegionBuffer or another LegionLOID.

LegionLOID()

Parameters: None

Not a very useful constructor, so it prints a warning and assigns all data members to zero. Useful constructors should at least say what the type is.

Accessors

Methods for getting and setting the type and all field values, by field number and field name, exist.

Overloaded operators

The == , != , and = operators are overloaded appropriately. An LOID is equal to another only if all fields are identical in size and value.

int is_empty()

Parameters: None

Returns 1 only if the LOID is of type UVaL_LegionLOID_type_EMPTY (zero).

int is_class()

Parameters: None

Returns 1 only if the LOID seems to refer to a class object, i.e. the instance number field is empty.

int same_class_as()

Parameters: UVaL_Reference<LegionLOID> other_loid

Returns 1 if the class_id field matches that of other_loid .

int pack()

LegionBuffer &lb

Type and num_fields are packed first, in network order. Next num_fields shorts are packed, in network order. Next, num_fields values are packed.

int unpack()

Parameters: LegionBuffer &lb

The type , num_fields , and field_size[] 's are unpacked into host order. The field_value[] 's are unpacked without switching the byte order.

int show()

Parameters: None

Prints the contents of the LOID to stderr for debugging purposes.

5.5 LegionMessage

LegionMessage()

Parameters: UVaL_Reference<LegionLOID> src

UVaL_Reference<LegionLOID> dest

int fnum

int parms_to_expect

UVaL_Reference<LegionComputationTag> tag

UVaL_Reference<LegionParameterList> plist

UVaL_Reference<LegionContinuationList> lcontList

UVaL_Reference<LegionEnvironment> lenv

The LegionMessage constructor creates a LegionMessage from the constituent parts passed as parameters.

Accessor functions

LegionMessage exports public member functions to get and set all of its constituent parts.

Overloaded operators

The equality operators ( == and != ) are overloaded. Two LegionMessages are deemed equal only if each of the constituent parts are equal, as determined by the equality operators of their respective classes.

show()

Parameters: None

Prints the contents of the LegionMessage to the stderr stream.

int pack()

int unpack()

Parameters: LegionBuffer &lb

LegionMessage is packable.

5.5.1 LegionParameter

LegionParameter()

Parameters: int param_number

UVaL_Reference<LegionBuffer> lb

Constructs a new parameter whose value is assumed to be in lb , and whose number is set to param_number .

Other constructors

The default constructor creates a parameter with a negative parameter number and an empty LegionBuffer . A constructor that takes only a LegionBuffer as a parameter unpacks the contents of the LegionParameter from that buffer. The copy constructor is also overloaded.

Accessor functions

LegionParameter exports public member functions to get and set both the parameter number and the buffer containing the value of the parameter.

Overloaded operators

The == operator is overloaded to return 1 when the parameter numbers are the same, and 0 otherwise.

show()

Parameters: None

Prints the contents of the LegionParameter to the stderr stream.

int pack()

int unpack()

Parameters: LegionBuffer &lb

LegionParameter is packable.

5.5.2 LegionParameterList

Constructors

The default constructor creates an empty parameter list, and a constructor that takes a LegionBuffer as an argument unpacks the contents of the LegionParameterList from that buffer.

Set operations

LegionParameterList is derived from templated class UVaL_PackableSet_LinkedList , and therefore exports the full interface of UVaL_PackableSet .

UVaL_Reference<LegionParameter> find()

Parameters: int parameter_number

Augments the UVaL_Set operations to allow parameters to be looked up by number. Returns a reference to the parameter, if found, or a null reference if not.

show()

Parameters: None

Prints the contents of the LegionParameterList to the stderr stream.

int pack()

int unpack()

Parameters: LegionBuffer &lb

LegionParameterList is packable.

5.5.3 LegionComputationTag

LegionComputationTag simply maintains a glorified interface to a long integer. The Library also contains a class -- LegionComputationTagGenerator -- that creates random computation tags. See the source code or on-line documentation for a description of that class.

Constructors

The default constructor creates a LegionComputationTag with an uninitialized initial value. A constructor that takes a LegionBuffer as an argument unpacks the contents of the computation tag from that buffer.

Accessor functions

LegionComputationTag exports public member functions to allow the value of the tag to be set and retrieved as a long integer.

show()

Parameters: None

Prints the contents of the LegionComputationTag to the stderr stream.

int pack()

int unpack()

Parameters: LegionBuffer &lb

LegionComputationTag is packable.

5.5.4 Other fields

A LegionMessage also contains a LegionContinuationList , and a LegionEnvironment . A LegionContinuationList is simply a UVaL_PackableSet of LegionContinuation s, and a LegionEnvironment is a UVaL_PackableSet of LegionEnvironmentItem s. Please refer to the on-line documentation and source code for the interface to these classes.

[an error occurred while processing this directive]