2.2 Calls on class objects

legion_activate_object 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Activates the object named in <object LOID> or <context path> (i.e., instantiates that object as a process) if it is inert. If the object is already active, the command has no effect.

The following options are supported:

legion_create_object
     {[-c] <class context name> | -l <class LOID>}
     <new object context path>
     [-h <host name on which to place new object>]
     [-v <vault on which to place new object>]
     [-H <context path of preferred host class>]
     [-V <context path of preferred vault class>]
     [-Ch <context containing list of preferred hosts>]
     [-Cv <context containing list of preferred vaults>]
     [-d <recorder context path> <debug session name>]
     [-debug] [-help]

Creates an instance of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object. The following options are supported:

If the -h flag isn't used, the host is selected by the class. Similarly, the class will choose a vault if the -v flag isn't used. Normally, this means that a random host is selected, but some classes may act differently. If the -Ch or -Cv flag is used, the class will randomly choose a host or vault from the hosts or vaults listed in the specified context. In both cases, the system will not return the LOID of the randomly chosen host. The legion_host_vault_list and legion_vault_host_list (page 40 and page 47) commands will allow users to limit the placement of a given class's instances (i.e., any instances of class Foo can only be placed on hosts X, Y, and Z).

legion_create_object_r 
     {[-c] <class context name> | -l <class LOID>} 
     <context path> <host name> <host architecture> 
     <$LEGION> <$LEGION_OPR> <$LEGION_OPA> 
     <binary path> [<user id>]
     [-debug] [-help]

Causes the specified class object to create a new object on the host named in <host name> using the rsh¹ (remote shell) mechanism. The object will be managed with rsh, if the class it is invoked on is an rshStartClass. If this utility is invoked on a normal class, normal object create mechanism will be used, and the object will not be managed by rsh. This command is generally used only by the legion_create_host and legion_create_vault scripts, not by users.

The additional arguments specify information for the rsh environment.

Optional parameters do the following:

legion_deactivate_object 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Deactivates the object named in <object LOID> or <context path> (moves it to an inert state) if it is currently active. If the object is already inactive, the command has no effect.

The following options are supported:

legion_destroy_object 
     {[-c] <object context name> | -l <object LOID>} [-debug] [-help]

Deletes the object named in <context path> or <object LOID>. More specifically, it removes the object's LOID but not its context name (if there is one). If the object is active, the command deactivates the object. In all cases, it deletes the OPR (object persistent representation) associated with the object.

This command will not remove any context name associated with the object: you must use the legion_rm command to remove the object's name(s) or you will get binding errors. (You can use legion_ls -A to check for multiple context names.)

The following options are supported:

legion_list_implementations 
     [-v] {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Lists the implementation objects associated with the class named in <class LOID> or <class context path>. In its default setting the output will consist of each implementation object's LOID and architecture type.

The following options are supported:

legion_list_instances 
     {[-c] <class context name> | -l <class LOID>} [-debug] [-help]

Displays information about the instances of the class named by <context path> or <class LOID>. For every instance, the tool displays the class's LOID, current object address, status (active or inert), the host on which it resides, and the vault that holds its OPR. The example below shows that class BasicFileClass has two instances, and that both are currently running.

$ legion_list_instances /class/BasicFileClass
Class 1.01.66000000..000001fc0d63e97... knows about the following instances:
LOID: 1.01.66000000.01000000.000001fc0a00...
        Current oa  : [xxx.xxx.xxx.xxx: 2020]
        Current host: 1.01.07.30232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status     : object-running
LOID: 1.01.66000000.02000000.000001fc0edd...
        Current oa : [xxx.xxx.xxx.xxx: 1895]
        Current host: 1.01.07.31232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status     : object-running
$

The following options are supported:

legion_set_host 
     {[-c] <instance context path> | -l <instance LOID>} 
     {[-c] <host context path> | -l <host LOID>} [-debug] [-help]

Calls the set_host() class-mandatory member function on the class of the instance named by in <instance LOID> or <instance context path>, causing the instance to migrate to the host named in <host LOID> or <host context path>.

In the example below, object Foo's host is changed from BootstrapHost to newHost.

$ legion_set_host -c Foo -c /hosts/newHost

The following options are supported:

legion_set_vault 
     {[-c] <instance context path> | -l <instance LOID>} 
     {[-c] <vault context path> | -l <vault LOID>} [-permanent]
     [-debug] [-help]

Migrates the state (OPR) of the object named in <instance LOID> or <instance context path> to the vault named in <vault LOID> or <vault context path>.

The following options are supported:

Be careful with the -permanent flag. If none of the instance's acceptable hosts match the chosen vault (i.e., there are no compatible host-vault pairs) the instance cannot be reactivated. Alternatively, the chosen vault may be compatible only with hosts for which the class has no implementation.

Please note that this command can fail for many reasons, including:

• the instance does not exist
• the user does not have permission to perform the migration
• the target vault does not exist
• the target vault will not grant the request to create a new OPR for the object
• the source vault is unavailable or will not grant the request to get the current OPR
• other machine or system failure
• the specified vault is unacceptable

The class object will enforce the current restrictions on its instance's acceptable vaults before it migrates the object's state. You may need to change the instance's list of acceptable vaults (via the legion_instance_vault_list command) to include the target vault before running legion_set_vault.

This command is not exactly the equivalent of a true object migration, since the object is not reactivated after its state is moved. Where the object reactivates depends on the scheduling decision made at the time the reactivation occurs. If the -permanent flag is not used and the instance's acceptable vault list is not otherwise altered, future activations of the instance may be on different vaults. If -permanent is used, all future activations must use the specified vault, until the acceptable vault list is altered.

1. If preferred, ssh can be used in place of rsh. Back

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