Legion 1.2
Basic User Manual

4.0 Context space

4.1 What is context space?

Context space is a way of organizing Legion space. It is similar to Unix's system of directories and files but while Unix space is location specific, context space can be arranged to suit the user's convenience. Contexts are string names assigned to Legion objects. The user can assign an object a name (or multiple names) without worrying about the object's physical location. Context space is organized into a series of sub-contexts, similar to Unix directories, and can be assigned mnemonic or logical names as suits the user. A single sub-context can contain context names that refer to objects located on a single machine or separated by large distances.

4.2 How context space works

All Legion objects are automatically assigned a unique system-level identifying name, called a LOID (Legion Object Identifier). The LOID allows the system to find objects scattered on several different machines. Since a LOID consists of several lines of numbers, it can be awkward at best for a user to track objects via their LOIDs. Users can instead assign a string name to an object's LOID, making it easier to find and use any object in Legion. This name, called a context name, resides only in a user's individual context space and refers only to a particular LOID. Context names are grouped into contexts and these contexts are organized into a hierarchy similar to a Unix directory structure.

Each user has a personal context space, which she organizes and maintains to suit her own needs. Objects are named according to each user's preferences, and each user's context space is independent of other users' context spaces, allowing different users to assign multiple context names to a single object without interfering with each other or with the object. This is discussed further in section "Organizing context space," but the next section provides a brief look at the anatomy of the LOID.

4.3 About the LOID

A LOID is a variable length binary structure (typically more than 128 bytes), which contains a type field followed by several variable size fields. The first variable field indicates the Legion domain in which the LOID was created, the second is the class identifier, the third is the instance number, and the fourth is a public key. The type, domain, and class identifier fields must be present. A LOID may be appended with any number of other fields, each of whose size and meaning are dependent on the LOID type. LOIDs are represented as strings, using standard "dotted hex" notation. For example, a typical LOID would look something like this:

1.01.07.01.000001fc0d24ab3512f63533f3f96b2bba0572aed8d
47efec7c24618fca3a3d49326fa84eaa320724c10264f225c97820
aced74586194974256ee86c2ae0565d55c8e623

In this sample the type field, 1, indicates the LOID's type; the first variable field, 01, indicates the domain in which the object was created; the second variable field, 07, indicates the class that the object belongs to; the third variable field, 01, indicates the object's instance number; and the fourth variable field, 000001fc0d24ab..., is the object's RSA public key. This notation is obviously too cumbersome for most users to manipulate as strings, so the naming service provided by context spaces allows users to deal with objects using meaningful string names chosen by the user. This separation of concerns between system-level names and user-level names allows Legion LOIDs to contain system-level information, such as an object's public key, without polluting the user-level name-space.

4.4 Organizing context space

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. Just as a Unix user organizes files in a series of directories, a Legion user organizes object in a series of contexts: a Legion system has a root context, and within that space each user has a personal root context, a home context in which he or she works.1 Users can use commands to move between contexts, just as they use commands to change directories in Unix space. A sample context space is shown in Figure 2.2 Notice that each user's context space is autonomous, so that the same name can be used by more than one user. E.g., User1 and User2 can create separate sub-contexts and call both of them ContextA. Note also that, depending on individual security arrangements, a user can work in another user's context space, just as Unix users can work in each other's directories.

Similarly, just as Unix users can use the same name in different directories to refer to different files, users can assign the same context name to different Legion objects: in Figure2 the path names /User1/ContextA/Foo and /User3/ContextC/ContextC1/Foo describe different context paths that can refer to different objects. The two users' context spaces are independent of each other, allowing the users to assign names without fear of conflict.

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

It is important to remember that context space does not reflect object space: ObjectX remains in its native location, regardless of any context path names users chose to give it. User1 might be in the same building as ObjectX or on the other side of the country. Context space is made up of string names organized by user preference. Objects named in a single context may actually be hundreds of miles apart.

Beyond this user-level grouping, 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 for users 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, one might enter a context called hosts, then a sub-context called ibm, then a sub-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_lookup, and legion_ context_list 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.

Objects contain in their state a root context (implicitly named "/") that provides each object with a base for absolute path names. The root context's LOID is stored in a variable that can altered by the object at runtime. Objects also contain in their state the current context's LOID, which provides the basis for relative context paths.3


1.The home context being discussed here should not be confused with the sub-context called home, one of the four basic sub-contexts provided in a new 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

3. It is important to note that this default path service provided by the Legion library is completely replaceable. For example, if a user wished to manipulate context spaces via DOS-style "\" delimited path names, the service could easily be implemented using the primitive context manipulation routines provided by the Legion library. Back


Back to Getting Started sectional index

Back to Basic User Manual Table of Contents