Tutorial:
Introduction to Legion 1.4 Context Space


Table of Contents

  What is context space?
What am I looking at?
Organizing context space

  Other relevant on-line documents:
  Logging in to a running Legion system
Legion graphical user interface
Introduction to Legion context space
Context-related commands
How to start remote programs in Legion
Object permissions
Legion tty objects
Running an MPI code in Legion
Running a PVM code in Legion
Quick list of all Legion commands
Usage of all Legion commands
Starting and shutting down Legion 1.4
Using Legion security features
Legion host and vault objects
Adding host and vault objects
The list of all on-line 1.4 tutorials


The Legion tutorials offer quick and simple instructions for various key procedures for a Legion system. More complete explanations of all of the procedures discussed here are available on separate pages, and can be found by clicking on the icon.

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a command such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh
The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.


What is context space?

Context space is a way of organizing Legion objects and can be thought of as a network-wide transparent file system. It is similar to Unix's system of directories and files but while Unix space is location specific, context space can potentially include objects anywhere in Legion. You maintain your own context space, organizing it to reflect your needs. You can use the Legion Context Manager (a graphical user interface) and command-line tools to organize this space.

You will probably spend a great deal of time working in context space, so it is important to understand the initial geography of your system's context space and how to negotiate that space. You will probably find this easier with the Context Manager: if you have not worked with this feature, click here to go an on-line tutorial or see the Basic User Manual.


What am I looking at?
Legion is an object-based system organized by classes and metaclasses (classes of classes). Every part of Legion, including classes and metaclasses, is represented by a Legion object. You manipulate these parts by controlling their representative objects. Objects are automatically assigned system-level names called Legion Object Identifiers (LOIDs) but LOIDs are difficult and awkward to use. Instead, Legion allows you to assign string names to any Legion objects and to organize those names according to your own preferences. New Legion systems include the basic outlines of context space but you can arrange your space as you wish. You can run programs, use remote resources, and take advantage of Legion's other features from your context space.

A typical newly installed system provides default contexts: there are four sub-contexts and several context names to allow you access to commonly used objects. Figure 1, below, shows the contents of a newly installed Legion system's context space. (Note that your context space will probably look different.)

Figure 1: Contents of a new Legion system context space

Think of the different levels of context space as directories and sub-directories. Each of the four contexts in Figure 1 can hold sets of sub-contexts, just as Unix directories hold sets of subdirectories. Context names are organized with contexts, just as Unix files are organized with directories. Context path names use Unix-style slash (/) as a default, so the examples here follow that style (e.g., the full context path name for BootstrapHost in the system shown in Figure 1 is /hosts/BootstrapHost). It is possible to change Unix-style slash to the DOS-style backslash (\) via the primitive context manipulation routines provided by the Legion library.

You can control your context space from a Context Manager. Or, you can work from the command line by using context-related command tools, discussed in a separate tutorial.

Figure 1 shows four sub-contexts: class, hosts, vaults, and home. These in turn contain the default context names of the basic elements of a new system: class contains context names of particular classes of Legion objects, hosts contains names of the host objects currently in your system, and vaults contains names of the vault object currently in your system. The home context is initially empty.

When newly installed, hosts contains two context names, BootstrapHost and the DNS name of the bootstrap host.1 Both of these names point to the bootstrap host object, which represents the bootstrap host. On the other hand, vaults contains only one context name, BootstrapVault, which points to the bootstrap vault object. (Please click here for more information on host and vault objects.)

A new class context contains context names for all of the basic Legion object classes, such as BasicFileClass and ttyObjectClass (Legion classes are themselves objects and can therefore be given context names). All Legion objects are organized into classes and all classes are organized into a hierarchy of metaclasses, with LegionClass as the supreme metaclass. Note that the context space illustrated in Figure 1 does not reflect this hierarchy. This is a key feature of context space: the physical location and organization of Legion objects is unrelated to any user's context space. The objects named in a host context do not have be able to communicate with each other or even to know of each other's existence. They do not even have to be host objects: you can organize your contexts as you wish.


Organizing context space Legion object names
More about the LOID

All contexts in Legion are organized into a Unix-like hierarchy, with a root context that contains a set of other contexts. This structure provides each object with an absolute path name (i.e., /mycontext/myobject). Just as a Unix user organizes files in a series of directories, a Legion user organizes objects in a series of contexts: you have a personal "root" context, a home context which acts like a home directory.2 You use commands to move between contexts, just as Unix users use commands to between directories. A sample context space is shown in Figure 2. Notice that the different users have autonomous context spaces. This allows the same name to be used by more than one user and in more than one context. E.g., User1 and User2 can create new sub-contexts and call both of them ContextA. Depending on individual security arrangements, just as Unix users can work in one another's directories one user can work in another user's context space.

Figure 2: Context space

Similarly, a context name can refer to different Legion objects, just as Unix users can use the same name in different directories to refer to different files: in Figure 11 the context path names /User1/ContextA/Foo and /User3/ContextC/ContextC1/Foo refer to different objects.

On the other hand, a single Legion object can have multiple context names in multiple contexts. Figure 3's Foo and Bar refer to a single object, ObjectX, but these names are in two different context spaces.

Figure 3: Single object with multiple context names

It is important to remember that context space does not reflect object space: ObjectX's native location is unchanged by its context path names. User1 might be in the same building as ObjectX or on the other side of the country. Objects named in a single context may actually be hundreds of miles apart.

Beyond the user-level grouping of individual context spaces, linking object groups in graph- or directory-based structures can be useful: just as a Unix directory tree or a collection of hypertext documents provide a logical means to organize information, context space provides a structure for finding and organizing Legion objects. For example, to find a host object running on an IBM SP2, you might enter a context called hosts, then a context called ibm, then a context called sp2, where a list of host objects running on SP2s could be found (in Unix, this would be the equivalent of moving through a series of directories--/hosts/ibm/sp2--to arrive at a directory called sp2).

Legion provides a library interface and utility commands such as legion_context_create, legion_context_add, and legion_ls for manipulating and negotiating context spaces. The Legion library interface provides a Unix-like path interface for expressing navigation through multiple contexts, and Legion command-line tools support path-like naming of objects within context space. Paths are delimited by the "/" character. For example, the path /usr/adam would map to the object named adam within the context named usr.


1. A host is a machine in a Legion system. A vault is a file storage system used to store inactive Legion objects. A host object represents and manages a given host in a Legion system, and a vault object represents and manages a given vault in a Legion system.[Back]

2. There is another context that represents the user's shell, but it does not appear in object path names nor does it affect the user's movements in context space.[Back]