4.5 The ensemblepattern

Ensemble is a representation of network hosts. It has the following attributes:

• hostname: The host name of the network host represented.
• createShell: Allows the creation of shells, i.e. processes, on the host represented by the ensemble. CreateShell is described in the next section.
• ns: A NameServer subpattern with added functionality. ns is described in more details below.

Never create ensemble instances on your own. The only sound way to obtain an ensemble reference is from shell.myEnsemble, ensemble.ns.get or by transferring ensemble references between shells.

4.5.1 CreateShell

Parameters to createShell are the expected qualification of the Shell created and the executable name from which to create it. Before using the execName name entered, it is appended to the value returned from the appsDir virtual, and $ signs in the resulting string expanded to the name of the target platform in lower case.

A number of virtuals defined locally to createShell allow the passing of parameters and environment variables to the newly created process. These virtuals are described below.

• appsDir: The appsDir virtual names the directory where executables are located. Default value is given by the shellEnv.defaultAppsDir virtual described in section 4.8. In order to override the default, further bind and assign a pathname to dir. The interpretation given to dir is described in section 4.8. Notice that the value of dir should be a full path.
• screenName: New shells created using createShell have no associated standard input or standard output. As a consequence, such shells are not allowed to read from standard in, and if they write to standard out or standard error, default is to redirect the output into some "black hole". On UNIX platforms a standard black hole is /dev/null. This default may be changed by further binding the screenName virtual, and assign a file name including full path to name. Further binding screenName overrides the defaultScreenName virtual of the new shell created. For more information on redirecting standard output, see section 4.9 describing the defaultScreenName virtual.
• environment: To set environment variables for the newly created shell, further bind the environment virtual and call addEnvVar for each environment variable to be added. For example:

(timeClient##,'timeClient')->myEnsemble.createShell (# environment:: (# do ('DISPLAY','blanche:0') -> addEnvVar #) #) -> newClient[];

• parameters should be further bound and addParam called for each command line parameter to be given to the new shell. For example:

(timeClient##,'timeClient')->myEnsemble.createShell (# parameters:: (# do '-serverName' -> addParam; 'daimi.aau.dk' -> addParam; #) #) -> newClient[];

4.5.2 CreateShell Implementation

Since the CreateShell Implementation in the distribution library is currently available only on UNIX platforms, the description in this section is UNIX specific. The implementation of CreateShell on e.g. a Macintosh target is different. See also section 5 that describes system dependencies.

Below, "old shell" refers to the shell executing a createShell, whereas "new shell" refers to the shell being created. Assuming the new shell is created on a remote host, CreateShell uses UNIX rsh to run the remoteStart script on the remote host. If the rsh process could not be forked, the processCreationFailed exception is raised. Thus, processCreationFailed signals lack of resources on the local host.

Otherwise, if forking rsh succeeds, the old shell reads from the standard output of the rsh process, i.e. what is written by the remoteStart script, to determine whether things went all right. remoteStart determines the target machine type and then executes the machine specific startAsDeamon executable. If the startAsDeamon executable or the shell executable could not be found, the execNotFound exception is raised. Errors different from processCreationFailed, relating to process start, raise the unknownError exception.

Finally, if the new shell process seems to have been successfully created, the thread in the old shell thread doing createShell waits for a callback from the new shell. If the callback ^[8] is not received within the time limit set by the active errorHandler, a timeOut exception is raised in that errorHandler. In the mean time, other threads in the old shell are allowed to do some work.

When the callback arrives, a reference to the new shell is included as a parameter. If the new shell does not qualify to the type entered as parameter to createShell, the typeError exception is raised.

The above description assumed that the target host was different from the local host. If the new shell is created on the local host, sh is used to execute the remoteStart script directly. That is, rsh is not used in the local case, making local createShell calls more efficient.

4.5.3 The ensemble.ns NameServer

• get: The primary responsibility of ns is to bind together all ensembles in the distributed environment. Thus, if ns.get is asked to look up an ensemble instance, the name parameter is expected to be an internet name, i.e. mjolner.dk, and the usual name services are used to determine the internet address of the corresponding network host. Using the expected port number of the ensemble process (see section 5.4 describing the ensemblePort virtual), ns.get is able to synthesize a reference to the ensemble requested. In addition, ns provides a flat namespace in which objects may be saved and retrieved using ns.put and ns.get.
• put: Saves the association between a textual name and an object reference entered as parameters. The overWrite virtual is called if an object of that name is already registered. If overWrite returns true, the existing (name,object reference) pair is overwritten with the new one.
• scanNames: Iterates over the names currently registered in the nameServer.