Legion 1.7 Reference Manual: 2.6 Scheduling support

2.6 Scheduling support

legion_add_sub_collection
      {-l <collection LOID> | -c <collection path>}
      {-l <member LOID> | -c <member path>} [-q <query>]

This command creates a new parent-subcollection relationship. A subcollection is a collection object that is polled by another collection object (called the parent collection) with a specified MESSIAHS-type query (see legion_query_collection, page 48, for details). If no query is specified, the default value of 'true' will be used. You can run this command multiple times to start multiple queries on a single subcollection.

A parent collection can have more than one subcollection and can run multiple queries on a single subcollection. A subcollection can have more than one parent as well as its own subcollections.

You must designate a parent collection (named in <collection LOID> or <collection path>). The member (named in <member LOID> or <member path>) is the subcollection. Both collections must already exist.

You can edit the collection_update_frequency_secs attribute with the legion_update_attributes command (page 10). E.g.,

$ legion_update_attributes -c /etc/Collection \
"collection_update_frequency_secs(600)"

will set the default collection to update itself every 10 minutes. The default setting is 300 seconds.

The following option is supported:

-q <query>

MESSIAHS-style query that will be run on the subcollection. The default selection is 'true'. See legion_query_collection (page 48) for details.

legion_class_host_list 
      [[-c] <class context name> | -l <class LOID>]
      [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] 
      [-debug] [-help]

Manipulates the list of hosts upon which the class named in <class context path> or <class LOID> can place its instances. The list of acceptable hosts for a given class consists only of hosts that have been added to the list. The list therefore may not necessarily include all possible hosts. If there are no hosts listed as acceptable the user can assume that all hosts are acceptable.

Note also that if you identify the class by its context name in the first parameter (i.e., myClass) you must use the hosts' context names in the [<host1> <host2> ... <hostn>] parameter. Similarly, if you name the class by its LOID (with the -l flag) you must use the hosts' LOIDs. If you were to enter:

$ legion_class_host_list /class/myClass \
   -t 1.01.07.d59d...

You would get an error message. Legion will treat the host's LOID as a context name.

The example below adds a new host to the list of acceptable hosts of BasicFileClass, using the -A flag.

$ legion_class_host_list /class/BasicFileClass \
   -a  /hosts/newHost
** ADDED 1 host(s) to class's acceptable host set

The -p flag can then be used to check the listing.

$ legion_class_host_list /class/BasicFileClass -p
** ACCEPTIBLE HOST LISTING: 
**      1.01.07.d59d1a40.000001fc094e23...
$

The following optional parameters are supported:

`-l`	Use dotted hex LOIDs to specify class and host.
`-a`	Add named host to the class's acceptable host list.
`-d`	Delete named host from the class's acceptable host list.
`-t`	Test whether or not a host is on the class's acceptable host list.
`-p`	Display the class's acceptable host list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results.

legion_class_vault_list 
      [[-c] <class context path> | -l <class LOID>}
      [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] 
      [-debug] [-help]

Manipulates the list of vaults upon which the class named in <class context path> or <class LOID> can place its instances' OPRs.

Note that if you identify the class by its context name in the first parameter (i.e., myClass) you must name the vaults by their context names in the [<vault1> <vault2> ... <vaultn>] parameter. Similarly, if you name the class by its LOID (with the -l flag) you must use the vaults' LOIDs. If you were to enter:

$ legion_class_vault_list /class/myClass -t 1.01.07.01000...

You would get an error message. Legion will treat the vault's LOID as a context name.

Optional parameters are:

`-l`	Use LOIDs to specify class and vault.
`-a`	Add named vault to the class's acceptable vault list.
`-d`	Delete named vault from the class's acceptable vault list.
`-t`	Test whether or not a vault is on the class's acceptable vault list.
`-p`	Display the class's acceptable vault list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results.

legion_config_scheduler 
      {[-c] <scheduler context path> | -l <scheduler LOID>} 
      [-get_enactor] [-get_collection] 
      [-set_enactor {[-c] <enactor context path> | -l <enactor LOID>}] 
      [-set_collection {[-c] <collection path> | -l <collection LOID>}]
      [-debug] [-help]

This command can be used to query or configure the helper objects used by a basic Legion scheduler. Basic Legion scheduler objects use a collection helper object to obtain information about available resources upon which they can schedule objects. After constructing a schedule, basic Legion schedulers use an enactor helper object to implement scheduling decisions (to actually start up the scheduled objects). Use this command to assign a particular collection and enactor to a basic Legion scheduler or vice versa.

The following optional parameters are supported:

`-get_enactor`	Print the LOID of a basic Legion scheduler's currently assigned enactor helper object.
`-get_collection`	Print the LOID of a basic Legion scheduler's currently assigned collection helper object.
`-set_enactor`	Set the enactor named in `<enactor LOID>` or `<enactor path>` to the scheduler.
`-set_collection`	Set the collection named in `<collection LOID>` or `<collection path>` to the scheduler.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_host_vault_list 
      {[-c] <host context path> | -l <host LOID>]
      [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] 
      [-debug] [-help]

Used to display and manipulate list of vaults with which the host named in <host context path> or <host LOID> can interoperate. Note also that if you identify the host by its context name in the first parameter (i.e., as foo) you must also identify the vaults by their context names in the [<vault1> <vault2> ... <vaultn>] parameter. Conversely, if you name the host by its LOID (via the -l flag) you must identify the vaults by their LOIDs. That is, you will get an error message if you mix LOIDs and context names:

$ legion_host_vault_list /host/HostName \
   -t 1.01.03.d49...

To list the vaults that a host can operate on use the -p flag:

$ legion_host_vault_list /hosts/HostName -p
** COMPATIBLE VAULT LISTING: 
**      1.01.03.d49d1a40.000001fc0a69cbb845...
$

The following optional parameters are supported:

`-l`	Use dotted hex LOIDs to specify host and vault.
`-a`	Add named vault to the host's acceptable vault list.
`-d`	Delete named vault from the host's acceptable vault list.
`-t`	Test whether or not a vault is on the host's acceptable vault list.
`-p`	Display the host's acceptable vault list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results.

legion_instance_host_list
      {[-c] <instance context name> | -l <instance LOID>}
      [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] 
      [-debug] [-help]

Manipulates the list of acceptable hosts upon which the instance can be placed. Note that if you use name the instance by its context path in the first parameter (i.e., as foo) you must name the hosts by their context paths in the [<host1> <host2> ... <hostn>] parameter. Conversely, if you identify the instance by its LOID in the first parameter (with the -l flag) you must use the hosts' LOIDs in the [<host1> <host2> ... <hostn>] parameter.

The following optional parameters are supported.

`-l`	Use LOIDs to specify instance and host.
`-a`	Add named host to the instance's acceptable host list.
`-d`	Delete named host from the instance's acceptable host list.
`-t`	Test whether or not a host is on the instance's acceptable host list.
`-p`	Display the instance's acceptable host list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_instance_vault_list
      {[-c] <instance context name> | -l <instance LOID>}
      [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] 
      [-debug] [-help]

Manipulates the list of acceptable vaults upon which the instance can be placed. Note that if you use name the instance by its context path in the first parameter (i.e., as foo) you must name the vaults by their context paths in the [<vault1> <vault2> ... <vaultn>] parameter. Conversely, if you name the instance by its LOID in the first parameter (with the -l flag) you must name the vaults by their LOIDs in the [<vault1> <vault2> ... <vaultn>] parameter.

The following optional parameters are supported.

`-l`	Use LOIDs to specify instance and vault.
`-a`	Add named vault to the instance's acceptable vault list.
`-d`	Delete named vault from the instance's acceptable vault list.
`-t`	Test whether or not a vault is on the instance's acceptable vault list.
`-p`	Display the instance's acceptable vault list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results.

legion_join_collection 
      {[-c] <collection context path> | -l <collection LOID>}
      {[-c] <member context path> | -l <member LOID>} 
      [-debug] [-help]

This command joins the objects named in <member LOID> or <member path> to the collection named in <collection LOID> or <collection path>. Any Legion object can be added to a collection.

You can use the legion_query_collection command (page 48) to get information (in the form of object attributes) about the given collection.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_leave_collection 
      {[-c] <collection context path> | -l <collection LOID>}
      {[-c] <member context path> | -l <member LOID>} 
      [-debug] [-help]

This command removes the object named in <member LOID> or <member path> from the collection named in <collection LOID> or <collection path>. The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

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

Lists all OPRs currently stored in a given vault. The output includes information about inert objects' LOIDs, OPA, owner, and status.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_list_sub_collections
      {-l <collection LOID> | -c <collection path>}

List a collection's set of subcollections and queries.

legion_make_schedule
      {-c <class context path> | -l <class LOID>}
      [-n <number of nodes>] [-f <specification file>]
      [-q <query>] [-help]

This command creates a host file for running an instance of the class named in <class context path> or <class LOID>. The host file is printed to stdout. The output of legion_make_schedule may be redirected into a file and used with the -HF flag in legion_mpi_run (see page 76).

The following options are supported:

`-n` `<number of nodes>`	Specify the number of nodes required for this run. Default is `1`.
`-f` `<specification file>`	Name a specification file that contains relative performance ratios for different architectures. E.g., the specification file could contain the lines: linux 1 alpha_linux 1.5 solaris 0.7
`-q` `<query>`	Specify a MESSIAHS query that can be used to prune the list of hosts on which the run can be scheduled.
`-help`	Print command syntax and exit.

legion_query_collection 
      [-v] 
      {[-c] <Collection context path> | -l <Collection LOID>} 
      <query> 
      [-debug] [-help]

This command searches for information of the collection object named in <collection LOID> or <collection path>. The format of the <query> string is described in the paper "Constructing Distributed Schedulers Using the MESSIAHS Interface Language," by Steve J. Chapin and Eugene H. Spafford.¹

Collection queries can be constructed using the interface below.

<query>	—>	<bool-expression>

<bool-expression>	—>	true \| TRUE \| True \| false \| FALSE \| False
	—>	<comparison-expr>

<comparison-expr>	—>	<expr> == <expr>
	—>	<expr> <= <expr>
	—>	<expr> >= <expr>
	—>	<expr> < <expr>
	—>	<expr> > <expr>
	—>	<expr> <> <expr>
	—>	<expr> != <expr>
	—>	<expr> or <expr>
	—>	<expr> xor <expr>
	—>	<expr> and <expr>
	—>	not <expr>
	—>	match (<string>, <string>)

<expr>	—>	<comparison-expr>
	—>	<int-const>
	—>	<oct-const>
	—>	<float-const>
	—>	<string>
	—>	$<identifier>
	—>	- <expr>
	—>	~ <expr>
	—>	<expr> + <expr>
	—>	<expr> - <expr>
	—>	max (<expr>, <expr>)
	—>	min (<expr>, <expr>)
	—>	<expr> / <expr>
	—>	<expr> * <expr>
	—>	<expr> mod <expr>
	—>	int (<expr>)
	—>	float (<expr>)
	—>	(<expr>)

<int-const>	—>	__any valid integer constant__

<oct-const>	—>	0[0-7]*

<float-const>	—>	__any valid float constant__

<string>	—>	".*"

<identifier>	—>	[a-zA-Z]+

Variables are of the form $VARNAME (e.g. $system_arch). The official variable names will be those exported by resource objects in their attributes. To get some idea of the current set of attributes, consult the documentation on resource objects (for the most up-to-date information, invoke the retrieve_all_attributes() method on a resource object and examine the results).

Examples of query strings are:

`'true'`	This query would return the list of all objects contained in the collection.
`'match($host_os_name,"SunOS")'`	This query would return the list of all objects contained in the collection with an attribute of the form (host_os_name,"SunOS").
`'match($host_os_name,"SunOS")'` or `'match($host_os_name,"Linux")'`	This collection would return the list of all objects contained in the collection with an attribute of either ($host_os_name,"SunOS") or ($host_os_name, "Linux").

The following option is available:

`-v`	Run in verbose mode. The resulting list of objects matching the query will be displayed along with the attributes of each object. Otherwise, only the list of matching objects (without their attributes) will be displayed.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

The example below uses the default collection (found in the /etc context), would be:

$ legion_query_collection /etc/Collection true
2 hits:
1.36ab9e4a.03.01000000.000001fc099204...
1.36ab9e4a.07.01000000.000001fc0d6e07...
$

The output shows that there are two objects in the collection, the bootstrap host and the bootstrap vault.

legion_remove_sub_collection
      {-l <collection LOID> | -c <collection path>}
      {-l <member LOID> | -c <member path>} [-q <query>]

This command ends a parent-subcollection relationship. It does not destroy either collection. You must name the parent collection and the subcollection. If the parent collection is running multiple queries on the subcollection, use the -q flag to stop a specific query (use legion_list_sub_collections, page 47, to see which queries are running on which subcollections). Otherwise, all queries will be stopped.

The following option is supported:

-q <query>

A MESSIAHS-style query that is being run on the subcollection. See legion_query_collection (page 48) for details.

legion_set_default_placement 
      {[-c] <class context path> | -l <class LOID>}
      {[-c] <host context path> | -l <host LOID>}
      {[-c] <vault context path> | -l <vault LOID>} 
      [-debug] [-help]

Sets the default placement for objects of the class named in <class LOID> or <class context name> to the given host/vault pair. Default placement is used when a class has no associated scheduler object or cannot contact its associated scheduler object. When a default placement is set the user should take care to ensure that an implementation for the default placement host's architecture is available.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

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

This commands sets the scheduler named in <scheduler LOID> or <scheduler context path> for the class named in <class LOID> or <class context path>. This will be the default scheduler for that class. The class will then use the scheduler to determine which hosts and vaults should manage its instances (i.e., determine placements for the class's instances).

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

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

This command can be used to set a class object's policy for using its default scheduler. See also legion_set_scheduler.

The legal values for <policy> are:

`0`	This policy value specifies that the class named in `<class LOID>` or `<class context path>` should use its default scheduler if the scheduler is currently active. It is intended to protect bootstrap classes, which may be involved in activating schedulers and scheduler helper objects. Typically, this policy is not recommended for user class objects.
	Classes using this policy should have a default placement available. See `legion_set_default_placement`.
`1`	This policy value specifies that the class should always use its default Scheduler, even if the Scheduler is not active. This is recommended for user classes, which usually require help from a Scheduler object when making placement decisions.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

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

Set a virtual host object's architecture. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). If the legion_set_varch command is not run, Legion will assume that the virtual host object's architecture is the same as its physical host.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

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

This command configures a virtual host object. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). Running this command indicates where the physical host can find scripts for starting and managing jobs on the virtual host. The <path> parameter is the local path for those scripts.

To configure a T3E virtual host object, you could run something like this:

$ legion_set_vrun /hosts/my_T3E $LEGION/src/T3E/SDSC

This tells Legion that the scripts are in $LEGION/src/T3E/SDSC.

The following options are supported:

`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

legion_vault_host_list
      {[-c] <vault context path> | -l <vault LOID>}
      [{-a | -d | -t} <host1> <host2> ... <hostn>] 
      [-p] [-debug] [-help]

Display and manipulates the list of hosts with which the vault named in <vault context path> or <vault LOID> can interoperate. Note that if you name the vault by its context name in the first parameter (i.e., myVault) you must use the hosts' context names in the [<host1> <host2> ... <hostn>] parameter. Similarly, if you name the vault by its LOID (with the -l flag) you must use the hosts' LOIDs.

To view the list of hosts that a given vault can operate on, you could use something like the example below.

$ legion_vault_host_list /vaults/VaultName -p
** COMPATIBLE HOST LISTING: 
**      1.01.07.d49d1a40.000001fc0c04724...
**      1.01.07.d59d1a40.000001fc094e23c...
**      1.01.07.d69d1a40.000001fc0b68108...
$

The following optional parameters are supported:

`-l`	Use LOIDs to specify vault and host.
`-a`	Add named host to the vault's acceptable host list.
`-d`	Delete named host from the vault's acceptable host list.
`-t`	Test whether or not a host is on the vault's acceptable host list.
`-p`	Display the vault's acceptable host list.
`-debug`	Catch and print Legion exceptions.
`-help`	Print command syntax and exit.

1. This paper is available on-line at <http://legion.virginia.edu/papers_abstracts.html#messiahs> back

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

Free JavaScripts provided by The JavaScript Source

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