Legion 1.6.3 Reference Manual: 6.0 Grid library

6.0 Grid library

The CLegionLib.h file contains the declarations for the C Library interface to the Legion system. This library is specifically designed to allow ease of use in many languages (including Fortran, C, C++). For additional functionality, the CError.h header file contains all necessary declarations to doing some small amount of error handling.

/* Change Log:     	*/
#ifndef CLEGION_LIB_H
#define CLEGION_LIB_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stdio.h>

Note that anytime this header file talks about freeing memory, it is referring to using the C-language's free() function to return memory to the heap, NOT the C++ language's delete operators.

/* LOID Parameters */
#define LOID_PARAM	0			/* These defines give the	*/
#define CONTEXT_PARAM	1			/* two valid values for 	*/
						/* LegionIdType variables	*/
						/* parameters.			*/

typedef	 int	LegionIdType;			/* This type is used in		*/
						/* function calls to indicate	*/ 
						/* whether or note the 		*/
						/* parameter is a LOID.  The	*/ 
						/* valid values are LOID_PARAM	*/
						/* and CONTEXT_PARAM.		*/

typedef	 int	CLegionBinding;			/* These typedefs are used to	*/
typedef	 int	CLegionHostReservation;		/* represent all of the	*/
typedef	 int	CLegionHostReservationRecord;	/* necessary C++ classes that	*/
typedef	 int	CLegionVaultReservation;	/* would normally be used in	*/
typedef	 int	CLegionVaultReservationRecord;	/* their place.  In all cases	*/
typedef	 int	CLegionReservation;		/* these are actually pointers	*/
typedef	 int	CLegionHostObjectStatus;	/* to LRefs to the actual	*/
typedef	 int	CLegionOPRAddress;		/* class type. This double	*/
typedef	 int	CUVaL_InstanceRecord;		/* level of pointer		*/
typedef	int	CInstancePlacementInfo;		/* indirection was done to 	*/
typedef	int	CLegionCollection Data;		/* allow for some small measure	*/
						/* of reference counting.	*/

The following section contains all of the valid Legion architectures.

#define LEGION_ARCH_linux		1
#define LEGION_ARCH_solaris		2
#define LEGION_ARCH_sun4		3
#define LEGION_ARCH_alpha_linux		4
#define LEGION_ARCH_alpha_DEC		5
#define LEGION_ARCH_sgi			6
#define LEGION_ARCH_rs6000		7
#define LEGION_ARCH_hp			8
#define LEGION_ARCH_t90			9
#define LEGION_ARCH_c90			10
#define LEGION_ARCH_t3e			11
#define LEGION_ARCH_x86_freebsd		12
#define LEGION_ARCH_winnt_x86 		13

All programs that use the CLegionLib library contain some small amount of state which determines how the CLegionLib library interacts with certain Legion functions. The following section gives the declarations for the functions that allow the user to interface with this state.

void	SetTimeOutValue		(int Seconds);	/* These functions set and clear	*/
void	ClearTimeOutValue	();		/* the default timeout value for	*/
						/* most Legion method invocations.	*/

void	SetForceActivation	();		/* In some small number of calls,	*/ 
void	ClearForceActivation	();		/* a target Legion object may not	*/ 
						/* not yet be active. The force		*/
						/* activation flag indicates		*/
						/* whether the call should  		*/
						/* activate the object or fail.		*/

void	SetTimeOutValue		(int Seconds);	/* These functions set and clear	*/
void	ClearTimeOutValue	();		/* the default timeout value for	*/
						/* most Legion method invocations.	*/

void	SetForceActivation	();		/* In a small number of calls, a	*/ 
void	ClearForceActivation	();		/* target Legion object may not		*/ 
						/* yet be active. The force		*/
						/* activation flag indicates		*/
						/* whether the call should 		*/
						/* activate the object or fail.		*/

6.1 Legion Library interface

The following section lists the functions which interface with the C++ Legion Library.

int
Legion_init();

Initializes the legion library (for a Legion object started by a Legion host, not for a command line object). This function, or one of the other init functions must be called in all Legion programs before any other Legion calls are made. This does not preclude calls to the CLegionLib which do not directly interact with Legion.

Parameters: None

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
Legion_init_with_class(char *ClassID, int ClassIdLen);

Initializes the Legion library (for a Legion object started as an instance of a certain Legion class, but perhaps started on the user's command line). This function, or one of the other init functions must be called in all Legion programs before any other Legion calls are made. This does not preclude calls to the CLegionLib which do not directly interact with Legion.

Parameters:
char* ClassID = The representation of the class which
instantiated the given object. These are
not strings so much as byte arrays.
int ClassIdLen = Length of the "byte" array given for
ClassID.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
Legion_init_command_line_class();

Initializes the legion library (for a Legion object started on the command line as a main Legion program). For most client tools, this version of create will be the one used. This function, or one of the other init functions must be called in all Legion programs before any other Legion calls are made. This does not preclude calls to the CLegionLib which do not directly interact with Legion.

Parameters: None

Return Values:
1 on Success
0 on Failure

User Responsibility: None

char*
Legion_GetLegionClassLOID();

Obtains the string representation of the LOID of the LegionClass object.

Parameters: None

Return Values:
LOID of the LegionClass object.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing memory allocated for the LOID.

CLegionBinding
Legion_GetLegionClassBinding();

Obtains the current binding for the LegionClass object.

Parameters: None

Return Values:
LegionBinding for LegionClass object

Error Return:
0

User Responsibility:
User is responsible for calling DestroyLegionBinding
on the returned binding when done with it.

int
Legion_AcceptMethods();

Enables the receipt of messages in the Legion library. This function must be called prior to any other function which might make outcalls to other objects, or receive methods or return values from any other objects.

Parameters: None

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
Legion_DeleteSelf();

Indicates to the object's (program's) class that the program is finished and ready to go away. After this function is called, the user's code may run for some undetermined amount of time, but will eventually be killed if it doesn't exit.

Parameters: None

Return Values:
1 on Success
0 on Failure

User Responsibility: None

void
Legion_Sleep(int secs);

Causes the user's code to pause for approximately. the number of seconds requested, while still handling external Legion events (such as method receives, exception receives, etc.).

Parameters:
secs = Number of seconds to sleep for.

Return Values: None

User Responsibility: None

char*
ClassOf(LegionIdType IdType, char *ObjName);

Returns the LOID of the indicated object's class.

Parameters:
IdType = Either CONTEXT_PARAM or
LOID_PARAM indicating what type of
string name is given next.
ObjName = Either a LOID, or a context path to an object

Return Values:
LOID of the indicated object's class.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the LOID return value.

char*
GetMyLOID();

Returns the LOID of the running object(program).

Parameters: None

Return Values:
LOID of the current running program.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the LOID return value.

6.2 Exceptions

The following section describes functions which interface with the Legion Exception interface.

extern int CLEGION_CONTINUE_ON_EXCEPTION;	  /* These variables correspond 	*/
extern int CLEGION_EXIT_ON_EXCEPTION;		  /* the valid values that can be	*/
extern int CLEGION_CANCEL_METHODS_ON_EXCEPTION;	  /* used as flags when enabling 	*/
extern int CLEGION_NO_MESSAGE_ON_EXCEPTION;	  /* an exception catcher.		*/

void
Legion_ExceptionCatcherDefaultEnable(int Flag);

Enables a default Legion Exception Handler with user indicated properties.

Parameters:
Flag = A value from the valid flags listed above which
indicates what the handler should do when a
Legion exception is caught. Valid values include:
CLEGION_CONTINUE_ON_EXCEPTION
CLEGION_EXIT_ON_EXCEPTION
CLEGION_CANCEL_METHODS_ON_EXCEPTION
CLEGION_NO_MESSAGE_ON_EXCEPTION
(Don't do anything)

Return Values: None

User Responsibility: None

6.3 Legion context space

The following section provides a C interface to Legion context space.

int
ContextSpaceActive();

Determines whether or not a valid context space exists.

Parameters: None

Return Values:
0 if Context space is NOT active
1 if Context space is active

User Responsibility: None

ContextLookup(char *LookupPath);

Look up the LOID of a name in the current context (does not allow paths in the name).

Parameters:
Context name of an object to look up in the
current context.

Return Values:
LOID of the object indicated context space.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the LOID return value.

char*
ContextPathLookup(char *LookupPath);

Look up the LOID of the object named in the given "Unix-like" context path. This command will allow both absolute, and relative naming.

Parameters:
Context path name of an object to look up in context space.

Return Values:
LOID of the object indicated context space.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the LOID return value.

char**
ContextMultiLookup(char *LkupPath);

Look up the LOIDs of a number of objects named in the current context (not path specified, however). It's somewhat confusing as to why this command takes a string at all, but the string basically needs to contain "*" as its parameter.

Parameters:
Unclear, but give it "*"

Return Values:
NULL terminated array of context space names for objects
in the indicated context. In other words, each element of
the array is a char*, which is either the context name of
an object, or NULL if it is the end of the list.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing each non-NULL entry in
the array, as well as the array itself.

char**
ContextPathMultiLookup(char *LkupPath);

Look up the LOIDs of a number of objects named in a "Unix-like" context path (absolute or relative path names are perfectly valid here). It's somewhat confusing as to what the parameter to this command means. Basically, the thing to do here is to indicate the context path you want a listing for, and append "/" and "*" to it.

Parameters:
Unclear, but basically the path you want a listing of
with "/ *" appended to it. I.e., if you want a
listing of /home/mark, the parameter should be
"/home/mark/ *".

(NOTE, in the above paragraph, there are spaces between
/ and * that should be removed. These are there to keep
the C compiler from thinking we are commenting.)

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing each non-NULL entry
in the array, as well as the array itself.

int
ContextAdd(char *Name, char *Loid);

Add an entry to the current context. This new entry will have the indicated name, and will point to the object with the given LOID. This command assumes that the name is in the current context (not a full path).

Parameters:
Name = The name to add to the current context
Loid = The LOID of the object to link into context
space.

Return Values:
1 on Success
0 on Failure

User Responsibility:
None

int
ContextRemove(char *Name);

Remove an entry from the current context. This entry must be in the current context. It cannot be a path name, but only a current context entry.

Parameters:
Name = The name to remove from context space.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ContextPathAdd(char *Name, char *Loid);

Add an entry to context space. This new entry will have the indicated name, and will point to the object with the given LOID. This command allows relative and absolute paths in context space to be added.

Parameters:
Name = The name to path to add to context space
LOID = The LOID of the object to link into context
space.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ContextPathRemove(char *Name);

Remove a path from context space.

Parameters:
Name = The path to remove from context space.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

char*
ContextSingleReverseLookup(
LegionIdType IdType, char *ObjName);

Try and obtain a context path name for a given object. This command uses the object's attributes to determine this name and only returns the first name found. Note that the attribute database may or may not actually reflect the object's actual context space names

Parameters:
IdType = Indicates whether the ObjName gives a
context path name or a LOID.
ObjName = Either the context name, or the LOID of the
object to reverse lookup.

Return Values:
First context path name of the object looked up.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the name returned.

char**
ContextMultiReverseLookup(
LegionIdType, char *ObjName, int MaxNum);

Try and obtain a list of context path names for a given object. This command uses the object's attributes to determine these names and only returns the first "MaxNum" entries found. Note that the attribute database may or may not actually reflect the object's actual context space names.

Parameters:
IdType = Indicates whether the ObjName gives a
context path name or a LOID.
ObjName = Either the context name, or the LOID of the
object to reverse lookup.
MaxNum = Maximum number of entries to return.

Return Values:
First "MaxNum" context path names of the object. These
paths are stored in a NULL terminated array of strings.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing each name returned in
the list well as the list itself.

char*
ContextPWD();

Return the context path name of the current context.

Parameters: None

Return Values:
context path name of the current context.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the context path name
returned.

char*
legion_mkdir(char *PathName);

Creates a new context named by the given path.

Parameters:
PathName = The new context's path name.

Return Values:
LOID of the new context that was created.

Error Return:
NULL

User Responsibility:
The user is responsible for "free"ing the context LOID.

int
legion_cd(char *PathName);

Change the current context to the one named in the path. NOTE that this only changes the current context for the running program, not for the shell or program that executed the program.

Parameters:
Pathname of the context to change to.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

6.4 Legion object management

The following section contains functions which are used to manage actual Legion Objects (create, activate, destroy, etc.).

int
ObjectActive(LegionIdType, char *Name);

Indicates whether the given object is currently active or inert.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either a context path name or a LOID.

Return Values:
1 if the object is active
0 if the object is inert

Error Return:
-1

User Responsibility: None

char*
Ping(LegionIdType, char *Name);

Ping a given object to see if it is responsive.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either a context path name or a LOID.

Return Values:
LOID of the object pinged.
Error Return:
NULL

User Responsibility:
User is responsible for "free"ing the LOID returned.

char**
Create(int NumObjects, LegionIdType, char* ClassName);

Create a vector of new Legion objects by vector instantiating the given class.

Parameters:
NumObjects = Number of object to vector instantiate.
IdType = Flag indicating whether the ClassName
parameter is a context path name or a LOID.
ClassName = LOID or context path name of the class to
instantiate.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is a
char* which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

char**
ScheduledCreate(int NumObjects,
LegionIdType CIDType, char* ClassName,
LegionIdType SIDType, char *SchedName);

Create a vector of new Legion objects by vector instantiating the given class. Used the given scheduler to schedule this vector instantiation.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is a
char* which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

char**
CreateRestricted(int NumObjects,
LegionIdType CIDType, char *ClassName,
LegionIdType HIDType, char *HostName,
LegionIdType VIDType, char *VaultName,
LegionIdType IIDType, char *ImplName);

Create a vector of new Legion objects by vector instantiating the given class. The user also indicates any combination of restrictions which may include restrictions to hosts, vaults or implementations.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is
a char* which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

char**
ScheduledCreateRestricted(int NumObjects,
LegionIdType CIDType, char *ClassName,
LegionIdType HIDType, char *HostName,
LegionIdType VIDType, char *VaultName,
LegionIdType IIDType, char *ImplName,
LegionIdType SIDType, char *SchedName);

Parameters:
NumObjects = Number of object to vector instantiate.
CIdType = Flag indicating whether the ClassName
parameter is a context path name or a LOID.
ClassName = LOID or context path name of the class to
instantiate.
HIdType = Flag indicating whether the HostName
parameter is a context path name or a LOID.
HostName = LOID or context path name of the Host to
restrict the instantiation to.
VIdType = Flag indicating whether the HostName
parameter is a context path name or a LOID.
VaultName = LOID or context path name of the Vault to
which the instantiation is restricted.
IIdType = Flag indicating whether the HostName
parameter is a context path name or a LOID.
ImplName = LOID or context path name of the
Implementation which the instantiation is
restricted.
SIdType = Flag indicating whether the SchedName
parameter is a context path name or a LOID.
ImplName = LOID or context path name of the Scheduler
to use when scheduling the instantiation.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is
a char* which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

char**
ComplxCreateRestricted(int NumObjects,
LegionIdType CIDType, char *ClassName,
LegionIdType HIDType, char **HostName,
LegionIdType VIDType, char **VaultName,
LegionIdType IIDType, char **ImplName);

Parameters:
NumObjects = Number of object to vector instantiate.
CIdType = Flag indicating whether the ClassName
parameter is a context path name or a LOID.
ClassName = LOID or context path name of the class to
instantiate.
HIdType = Flag indicating whether the HostName
parameter is a NULL terminated list of
context path names or a NULL terminated
list of LOIDs.
HostName = NULL terminated array of LOIDs or context
path names of the Hosts to which the
instantiation is limited.
VIdType = Flag indicating whether the VaultName
parameter is a NULL terminated list of
context path names or a NULL terminated
list of LOIDs.
VaultName = NULL terminated array of LOIDs or context
path names of the Vaults to which the
instantiation is restricted.
IIdType = Flag indicating whether the ImplName
parameter is a NULL terminated list of
context path names or a NULL terminated
list of LOIDs.
ImplName = NULL terminated array of LOIDs or context
path names of the Impls to which the
instantiation is restricted.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is a
char* which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

char**
ComplxScheduledCreateRestricted(int NumObjects,
LegionIdType CIDType, char *ClassName,
LegionIdType HIDType, char **HostName,
LegionIdType VIDType, char **VaultName,
LegionIdType IIDType, char **ImplName,
LegionIdType SIDType, char *SchedName);

Parameters:
NumObjects = Number of object to vector instantiate.
CIdType = Flag indicating whether the ClassName
parameter is a context path name or a LOID.
ClassName = LOID or context path name of the class to
instantiate.
HIdType = Flag indicating whether the HostName
parameter is a NULL terminated list of
context path names, or a NULL terminated
list of LOIDs.
HostName = NULL terminated array of LOIDs or context
path names of the Hosts to which the
instantiation is restricted.
VIdType = Flag indicating whether the VaultName
parameter is a NULL terminated list of
context path names, or a NULL terminated
list of LOIDs.
VaultName = NULL terminated array of LOIDs or context
path names of the Vaults to which the
instantiation is restricted.
IIdType = Flag indicating whether the ImplName
parameter is a NULL terminated list of
context path names, or a NULL terminated
list of LOIDs.
ImplName = NULL terminated array of LOIDs or context
path names of the Impls to which the
instantiation is restricted.
SIdType = Flag indicating whether the SchedName
parameter is a context path name or a LOID.
SchedName = context path name or LOID of the
scheduler to use when instantiating the
class.

Return Values:
NULL terminated array of LOIDs indicating the objects
that were instantiated. Each element of the array is a char*
which is the LOID of one object created.

Error Return:
NULL

User Responsibility:
User is responsible for "free"ing each LOID in the array
as well as the array itself.

int
Activate(LegionIdType IType, char *ObjectName);

Activate an inert Legion object

Parameters:
IdType = Flag indicating whether the ObjectName
parameter is a context path name or a LOID.
ObjectName = LOID or context path name of the object to
activate.

Return Values:
1 on Success
0 on failure

User Responsibility: None

int
ScheduledActivate(LegionIdType OIDType, char *ObjectName,
LegionIdType SIDType, char *SchedName);

Activate an inert Legion object (using the indicated scheduler to schedule the activation)

Parameters:
OIDType = Flag indicating whether the ObjectName
parameter is a context path name or a LOID.
ObjectName = LOID or context path name of the object to
activate.
SIdType = Flag indicating whether the SchedName
parameter is a context path name or a LOID.
SchedName = LOID or context path name of the
scheduler to use when doing the activation.

Return Values:
1 on Success
0 on failure

User Responsibility: None

int
ActivateRestricted(LegionIdType OIDType, char *ObjectName,
LegionIdType HIDType, char *HostName,
LegionIdType VIDType, char *VaultName,
LegionIdType IIDType, char *ImplName);

Activate an inert Legion object, but subject to the restrictions indicated by the user.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ScheduledActivateRestricted(
LegionIdType OIDType, char *ObjectName,
LegionIdType HIDType, char *HostName,
LegionIdType VIDType, char *VaultName,
LegionIdType IIDType, char *ImplName,
LegionIdType SIDType, char *SchedName);

Activate an inert Legion object, but subject to the restrictions indicated by the user. Also, use the indicated scheduler to schedule the activation.

Parameters:
OIDType = Flag indicating whether the ObjectName
parameter is a context path name or a LOID.
ObjectName = LOID or context path name of the object to
activate.
HIdType = Flag indicating whether the HostName
parameter is a context path name or a LOID.
HostName = LOID or context path name of the Host to
which the activation is restricted.
VIDType = Flag indicating whether the VaultName
parameter is a context path name or a LOID.
VaultName = LOID or context path name of the Vault to
which the activation is restricted.
IIDType = Flag indicating whether the ImplName
parameter is a context path name or a LOID.
ImplName = LOID or context path name of the Impl to
which the activation is restricted.
SIDType = Flag indicating whether the SchedName
parameter is a context path name or a LOID.
SchedName = LOID or context path name of the
Scheduler to use when doing the activation.

Return Values:
1 on Success
0 on failure

User Responsibility: None

int
ComplxActivateRestricted(
LegionIdType OIDType, char *ObjectName,
LegionIdType HIDType, char **HostName,
LegionIdType VIDType, char **VaultName,
LegionIdType IIDType, char **ImplName);

Activate an inert Legion object, but subject to the restrictions indicated by the user.

Parameters:
OIDType = Flag indicating whether the ObjectName
parameter is a context path name or a LOID.
ObjectName = LOID or context path name of the object to
activate.
HIdType = Flag indicating whether the HostName
parameter is a list of context path names or
LOIDs.
HostName = A NULL terminated array of LOIDs or
context path names of Hosts to which the
activation is restricted.
VIdType = Flag indicating whether the VaultName
parameter is a list of context path names or
LOIDs.
VaultName = A NULL terminated array of LOIDs or
context path names of Vaults to which the
activation is restricted.
IIdType = Flag indicating whether the ImplName
parameter is a list of context path names or
LOIDs.
ImpleName = A NULL terminated array of LOIDs or
context path names of Implementations to
which the activation is restricted.

Return Values:
1 on Success
0 on failure

User Responsibility: None

int
ComplxScheduledActivateRestricted(
LegionIdType OIDType, char *ObjectName,
LegionIdType HIDType, char **HostName,
LegionIdType VIDType, char **VaultName,
LegionIdType IIDType, char **ImplName,
LegionIdType SIDType, char *SchedName);

Activate an inert Legion object, but subject to the restrictions indicated by the user and using the given scheduler.

Parameters:
OIDType = Flag indicating whether the ObjectName
parameter is a context path name or a LOID.
ObjectName = LOID or context path name of the object to
activate.
HIdType = Flag indicating whether the HostName
parameter is a list of context path names or
LOIDs.
HostName = A NULL terminated array of LOIDs or
context path names of Hosts to which the
activation is restricted.
VIdType = Flag indicating whether the VaultName
parameter is a list of context path names or
LOIDs.
VaultName = A NULL terminated array of LOIDs or
context path names of Vaults to which the
activation is restricted.
IIdType = Flag indicating whether the ImplName
parameter is a list of context path names or
LOIDs.
ImpleName = A NULL terminated array of LOIDs or
context path names of Implementations to
which the activation is restricted.
SIDType = A flag indicating whether the SchedName
parameter is a context path name or a LOID.
SchedName = A context path name or LOID indicating the
scheduler to use when doing the activation.

Return Values:
1 on Success
0 on failure

User Responsibility: None

int
DeleteObject(LegionIdType IdType, char *ObjName);

Deletes or Destroys a given object by asking its class to get destroy it. This function is identical to DestroyObject

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either the context path name or the LOID
of the object to delete.

Return Values:
1 on Success
0 on Failure

User Responsibility:
None

int
DestroyObject(LegionIdType IdType, char *ObjName);

Deletes or Destroys a given object by asking its class to get destroy it. This function is identical to DeleteObject

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either the context path name or the LOID
of the object to destroy.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
DeactivateObject(LegionIdType IdType, char *ObjName);

Deactivates a given object.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either the context path name or the LOID
of the object to deactivate.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ForcedDeactivateObject(LegionIdType IdType, char *ObjName);

Deactivates a given object. The forced in this call means that if the object is going up or going down, then an error is returned.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
Name = Either the context path name or the LOID
of the object to deactivate.

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
GetObjectType(LegionIdType IdType, char *ObjName);

Returns an integer which indicates as specifically as possible what type of object the user is talking about.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path.
ObjName = Either the context path name or the LOID
of the object to be described.

Return Values:
Returns an integer indicating the type of the object (from the
list above).

User Responsibility: None

#define	LEGION_OBJ_CONTEXT		1	/* These constants are used	*/
#define	LEGION_OBJ_FILE			2	/* to indicate what type of	*/
#define	LEGION_OBJ_RUNNABLE		3	/* object one is talking	*/
#define	LEGION_OBJ_CLASS		4	/* about. These are the 	*/
#define	LEGION_OBJ_HOST			5	/* values that can be 		*/
#define	LEGION_OBJ_VAULT		6	/* by GetObjectType().		*/
#define	LEGION_OBJ_TTY			7
#define	LEGION_OBJ_IMPLEMENTATION	8
#define	LEGION_OBJ_IMPLEMENTATION_CACHE	9
#define	LEGION_OBJ_LEGION_CLASS		10
#define	LEGION_OBJ_BINDING_AGENT	11
#define	LEGION_OBJ_MPI			12
#define	LEGION_OBJ_PVM3			13
#define	LEGION_OBJ_UNKNOWN		14

int
isContext(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a context object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a context
0 if the object is not a context

User Responsibility: None

int
isFile(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a File object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a File
0 if the object is not a File

User Responsibility: None

int
isRunnable(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a Runnable object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = Either the context path name or the LOID
of the object to test.

Return Values:
1 if the object is a Runnable
0 if the object is not a Runnable

User Responsibility: None

int
isClass(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a Class object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a Class
0 if the object is not a Class

User Responsibility: None

int
isHost(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a Host object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a Host
0 if the object is not a Host

User Responsibility: None

int
isVault(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a Vault object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a Vault
0 if the object is not a Vault

User Responsibility: None

int
isTTY(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a TTY object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a TTY
0 if the object is not a TTY

User Responsibility: None

int
isImplementation(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a Implementation object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a Implementation
0 if the object is not a Implementation

User Responsibility: None

int
isImplementationCache(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a ImplementationCache object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a ImplementationCache
0 if the object is not a ImplementationCache

User Responsibility: None

int
isLegionClass(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a LegionClass object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a LegionClass
0 if the object is not a LegionClass

User Responsibility: None

int
isBindingAgent(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a BindingAgent object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a BindingAgent
0 if the object is not a BindingAgent

User Responsibility: None

int
isMPI(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a MPI object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a MPI
0 if the object is not a MPI

User Responsibility: None

int
isPVM3(LegionIdType IdType, char *ObjName);

Determines if the indicated object is a PVM3 object or not.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to test.

Return Values:
1 if the object is a PVM3
0 if the object is not a PVM3

User Responsibility: None

6.5 Legion attributes

The following functions deal with the attribute database that all Legion objects support.

int
AddAttribute(
LegionIdType IdType, char *ObjName, char *Attribute);

Add an attribute to an object's attribute database.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to which the attribute is to be added.
Attribute = The string representation of the attribute to
add to the database. This is of the form
attribute_signature(attribute_value).

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
AddAttributes(
LegionIdType IdType, char *ObjName, char **Attribute);

Add a list of attributes to an object's attribute database.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to which the attribute will be added.
Attribute = A NULL terminated list of the string
representations of the attributes to add to
the database. These are of the form
attribute_signature(attribute_value).

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ReplaceAttribute(LegionIdType IdType,
char *ObjName, char *OldAttribute, char *NewAttribute);

Replace an attribute in an object's attribute database.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to which the attribute will be added.
OldAttribute = The string representation of the old
attribute to replace in the database. This is
of the form
attribute_signature(attribute_value).
NewAttribute = The string representation of the new
attribute to put into the database. This is of
the form
attribute_signature(attribute_value).

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ReplaceAttributeSig(LegionIdType IdType,
char *ObjName, char *OldAttributeSig, char *NewAttribute);

Replace an attribute in an object's attribute database.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.
ObjName = The context path name or the LOID of the
object to which the attribute will be added.
OldAttributeSig = The string representation of the old
attribute's attribute signature.
NewAttribute = The string representation of the new
attribute to put into the database. This is of
the form
attribute_signature(attribute_value).

Return Values:
1 on Success
0 on Failure

User Responsibility: None

int
ReplaceAttributes(LegionIdType IdType,
char *ObjName, char **OldAttributes, char **NewAttributes);

Replace a list of attributes in an object's attribute database.

Parameters:
IdType = Flag indicating whether parameter is a
LOID or a context path name.