Legion version 1.3 and forward support the concept of linking together discrete Legion systems. Previously, each was an isolated entity: objects running in one system could not communicate with objects running in another system. In current versions, each Legion system constitutes its own domain: a domain contains all features necessary for running any Legion application and can be run autonomously. However, multiple domains can be combined to form a larger virtual machine. Objects created in one of these domains can communicate with and use the services of other objects in connected domains.
A domain is automatically assigned system-level a domain identifier when it is first created (i.e., when a new Legion system is configured with the legion_setup_state command). The domain identifier is a variable-length field of bytes. It is embedded into all of the domain's Legion object identifiers (LOIDs) as the second field. For example, the domain below has a one-byte domain-id, c8:
All class objects in a domain will use the same domain identifier when assigning new objects LOIDs. You can specify the identifier if legion_setup_state is run interactively (with the -i flag). Otherwise Legion will select a four-byte domain-id. Once the domain-id has been assigned, it cannot be changed.
To locate an object in another domain you must contact the domain's binding services, which can then track down the object's LOID and location. However, if you know the domain's LegionClass's binding (i.e., the LOID and Object Address of the domain's metaclass) you can find the domain's binding services.
The LegionClass's binding is found in a file called LegionClass.config in each domain's $LEGION_OPR directory. The LegionClass.config file is a LegionBuffer, however, and to mask the data format of the file's contents the file is accompanied by a file called LegionClass.config._LegionStorage _MetaData_. If the metadata file is not present the LegionClass.config file may be unreadable.
Legion domains can be combined together to form larger systems with legion_combine_domains. This tool connects your current domain (i.e., the one in which you execute the command) to a specified target domain. If other domains have already been connected to either your current domain or to the target domain, they will be part of the new multidomain system as well.
To perform this operation, the tool makes the domains' LegionClass objects aware of one another. In practice, this involves determining the bindings of all of the involved LegionClass objects and broadcasting the complete binding set to all of the LegionClass objects. Once this operation has been performed, the binding trees of the different domains will be connected. In effect, the set of joined LegionClass objects represent a distributed class-map. Binding traffic that reaches LegionClass in your current domain but is related to another domain will be forwarded to the LegionClass object in the appropriate domain. Binding caches and the class-of operations involved in the binding process will minimize the need for interdomain binding-related traffic between LegionClass objects). As in earlier versions of the system, the global (now distributed) class-map in Legion is protected from contention by heavy caching.
To do its job, legion_combine_domains needs to have information about each domain that it will be linking. If Legion security is turned on in any of the involved domains it will also need security credentials for each secure domain in order to authorize it to link external domains. This domain information is stored in the form of a domain cookie. A domain cookie is simply a file holding the needed binding information and security credentials for a single Legion domain. The legion_generate_domain_cookie command creates a cookie file and legion_print_domain_cookie displays it.
There are four commands related to Legion domains. The legion_list_domains command lists the set of domains currently connected to your domain, legion_combine_domains connects domains, legion_generate_domain_cookie generates a domain cookie for a domain, and legion_print_domain_cookie displays the cookie.
You can use the legion_list_domains command to view a list of those domains connected to your current domain. The output will list your current domain's binding and any domains linked to your current domain.
This output shows that there are two domains and lists each domain's binding (its LegionClass object's LOID and OA). The current domain is listed first. Note that the domains' identifier can be seen in the second field of the two LegionClass LOIDs: the first is 35d82a07 and the second is c8.
The cookie contains binding information for your domain's LegionClass, security credentials, and information about your domain's context space. By default, the new cookie file will be named LegionDomainCookie.<domain-id>. Use the -o flag to specify a different name.
The legion_print_domain_cookie command will display the contents of a Legion domain cookie file. By default, the command will display the contents of LegionDomainCookie.<domain-id>. Use the -i flag to specify a different cookie filename.
The legion_combine_domains tool connects Legion domains together into a single, larger Legion system. Once joined, objects in connected domains can communicate with each other as easily as objects in a single domain communicate with each other. Usage of this command is:
Before you run legion_combine_domain, you must obtain a copy of the domain cookie files from all of the domains involved (i.e., if you wish to join a multidomain system you must have copies of all of the domains' cookie files).