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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-h

Specify a host for the new object.

-v

Specify a vault for the new object.

-H

Specify the preferred host class's context path.

-V

Specify the context path of the preferred vault.

-Ch

Specify a context which contains a list of the preferred hosts.

-Cv

Specify a context which contains a list of the preferred vaults.

-d

Automatically start a legion_record session for the newly created object. This allows you to debug server objects. The object's relevant activity will be recorded by a previously started Legion recorder object, named in <recorder context path>.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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 rsh1 (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.

<host name>

Specifies the host upon which the new object should be placed. Note that this should be a DNS name.

<host architecture>

Specifies the host's architecture.

<$LEGION>

Specifies the Legion environment variable on the rsh host.

<$LEGION_OPR>

Specifies LEGION_OPR for host.

<$LEGION_OPA>

Specifies the OPR address for the object, i.e, a unique directory in which the object will maintain its persistent representation on the remote host.

<binary path>

Binary executable path for the object on the remote host.

Optional parameters do the following:

<user id>

Specifies the appropriate user name on the rsh host.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-v

Run the command in a verbose setting. The output will include byte size and a brief description of each object. Legion will use one extra method invocation per implementation object.

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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:

-permanent

Makes the migration permanent. I.e., the object's acceptable vault list will be change to list only the new vault. No further migration can occur without user intervention via legion_instance_vault_list (see page 41).

-debug

Catch and print Legion exceptions.

-help

Print command syntax and exit.

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

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

Free JavaScripts provided by The JavaScript Source

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