Starting and Shutting down Legion 1.0

Where can the start-up procedure be run?

Note that, while the sample start-up below uses a single machine for convenience, you are not required to use the same machine for all three steps. Technically, there are two processors (called hosts in Legion) used for the whole procedure, the start-up host and the bootstrap host (Figure 1, below), but you can carry out all three steps on a single host.

Figure1: Division of labor on the start-up and bootstrap hosts

In either case, Legion binary executable files must be installed on any hosts used for Legion procedures. The host that you select during legion_setup_state and that contains the basic Legion classes is the start-up host. The start-up host must always be used to run legion_startup. The bootstrap host is used to boot the system and is the first host object added to the system. It will contain the first pieces of the new system (the first contexts and instances of the classes). You do not have to run legion_initialize on the same host on which you run legion_setup_state and legion_startup.

What does legion_setup_state do?
This command sets up the initial state for core Legion system objects. These core objects are the building blocks of a new system, and need to be properly configured before they can be started. Once the system is running these objects will manage their own state and configuration, if the system is properly maintained.

The legion_setup_state program will prompt for the host name and a port number for the LegionClass object. If you wish to use your current host as the start-up host, a random port, and the current time, which should be acceptable, hit the return key.

The script creates a directory called OPR along with several sub-directories, and populates them with initial states for core system objects. The OPR directory will be created in the Legion root directory. The timestamp sets the starting time for the system: Legion objects use a timestamp to guarantee each object's unique identity. The current time is measured in seconds since Jan. 1, 1970.

What does legion_startup do?
As the name implies, this command starts up major classes such as LegionClass and BootstrapMetaClass that are responsible for tracking and controlling core objects. Note that the output describes these classes as class objects; in Legion, an object-based system, all classes are themselves objects and must therefore be started up. The legion_startup script is essentially a tool for starting these objects from the command line in a single step.

What does legion_initialize do?
This rather lengthy output shows the system creating and tagging the key ingredients of a new system. The first lines
Creating host object BootstrapHostObject on 
Continue (y=yes, Y=yes to all, n=no, N=no to all, v=verbose, V=verbose all)? Y
Configuring wellknown binaries for host ""
shows the system creating the BootstrapHostObject on your current host (i.e., your machine or processor). Whatever host you run legion_intitialize on will be considered the bootstrap host. The host object is a Legion object that represents and manages a host in a Legion system, so the BootstrapHostObject represents the current (bootstrap) host.

Next, a bootstrap vault object is automatically created on your current host. This object will represent and manage your bootstrap vault, which is essentially a storage space used to store the state of inactive Legion objects.

Creating vault object BootstrapVaultObject on
Setting BootstrapHost and BootstrapVault restrictions
Added 1 host(s) to vault's compatibility set
Added 1 vault(s) to host's compatibility set
In Legion, a host object must have an compatible vault object on which to store the state of its inactive objects, so the bootstrap host and vaults are marked as compatible. In Legion a host and vault are considered compatible when they can "see" each other: that is, they must be able to communicate with each other.

The system then creates objects which will represent and manage the implementation cache (used by host objects to execute copies of Legion programs in different architectures) and context space.

Creating an ImplementationCache
Creating an implementation (ContextObject) for ContextClass
Creating the root context object
The next piece of information is simply a reminder to set the environment variables before running any commands. You may not have to do this, depending on how your system is set up.
Be sure to
        source /home/xxxx/OPR/legion_context_env.csh
        . /home/xxxx/OPR/
before starting anything else from the command line.
The next line of the output,
Deactivating BootstrapHostObject
is merely announcing that the object representing the bootstrap host is temporarily shutting down: it immediately reactivates, although the output does not show this.

The remainder of the output shows various key objects being created and the basic elements of the system's context space being set up. This space is similar to a Unix directory and file system: the three initial contexts, class, hosts, and vaults are akin to directories, and contain context names (similar to file names in Unix) that refer to Legion objects. Figure 2, below shows the contents of a typical newly created Legion system. For more information on Legion context space, please see "Legion Context Space".

Figure 2: Context space of a newly initialized Legion system