Eli   Documents
Eli: Translator Construction Made Easy

General Information

o Eli: Translator Construction Made Easy
o Global Index
o Frequently Asked Questions
o Typical Eli Usage Errors

Tutorials

o Quick Reference Card
o Guide For new Eli Users
o Release Notes of Eli
o Tutorial on Name Analysis
o Tutorial on Scope Graphs
o Tutorial on Type Analysis
o Typical Eli Usage Errors

Reference Manuals

o User Interface
o Eli products and parameters
o LIDO Reference Manual
o Typical Eli Usage Errors

Libraries

o Eli library routines
o Specification Module Library

Translation Tasks

o Lexical analysis specification
o Syntactic Analysis Manual
o Computation in Trees

Tools

o LIGA Control Language
o Debugging Information for LIDO
o Graphical ORder TOol

o FunnelWeb User's Manual

o Pattern-based Text Generator
o Property Definition Language
o Operator Identification Language
o Tree Grammar Specification Language
o Command Line Processing
o COLA Options Reference Manual

o Generating Unparsing Code

o Monitoring a Processor's Execution

Administration

o System Administration Guide
Mail Home

Eli System Administration Guide

Previous Chapter Next Chapter Table of Contents

Odin Execution

Odin is designed according to a client/server architecture. The server is responsible for maintaining the cache, and the client is responsible for interacting with the user and executing those tools not built into Odin. Normally the client and the server run as separate processes, possibly on different machines, communicating via network sockets.

Client execution

When you give an eli command, it starts an Odin client. The client determines a specific cache from the command (see Name of the cache). It then checks that cache to see whether a socket is associated with it. If not, the client establishes a socket for the cache and forks (see Interprocess communication). The forked process becomes the server for that cache, and listens for clients on the socket.

The client connects to the server via the socket. It continues to interact with you, accepting input and delivering reports. Whenever you make a request, the client packages that request and forwards it to the server. If the server needs to invoke a tool that is not built into Odin, then it sends an appropriate command line to the client to be executed.

Each client may have a colon-separated list of machines as the value of its BuildHosts variable (see Buildhosts Maxbuilds of Eli User Interface Reference Manual). The name LOCAL refers to the machine running the client; it is assumed if no list is given. The client executes the command line given it by the server on the first machine in the list that does not have a currently executing command.

When the client terminates, either because you have responded to a prompt with C-d or because the end of the input file has been reached in a batch run, it informs the server of this termination.

Server execution

A server is associated with a specific cache. The first client started on that cache creates the server by forking (see Client execution). Subsequent clients started on that cache do not fork new servers, but connect to the existing server via the socket already established for the cache. When all clients connected to the server have terminated, the server itself terminates and closes the socket.

The server for a cache receives all requests involving that cache, and is responsible for ensuring that requests involving specific files are sequenced so that all requests are effectively atomic.

Tools built into Odin are also executed by the server. If a client request requires execution of an external tool, the server builds a command line invoking the tool and passes it to the first client that is not currently executing such a command line. Thus the server may involve a client in running tools necessary to satisfy requests from other clients.

Interprocess communication

When a client is started on a cache (see Client execution), it checks whether the cache contains a file named `SOCKET'. `SOCKET' is normally a text file containing a single line giving the name of the machine on which the server is running and the port number to which it is listening (but see Socket implementation). If `SOCKET' is not present, then the client creates it and forks a new server for the cache.

The client creates `SOCKET' by opening it with the O_CREAT and O_EXCL flags. If two or more clients are started simultaneously on a cache with no servers, and all attempt to create `SOCKET', this combination of flags ensures that only one of the create operations can succeed. Thus one of the clients will create the socket file and fork the server, while the file creation will fail on the others. After the client has determined that a server is present, or after its file creation fails, or after it has successfully forked a server, it connects to the socket defined by the cache's `SOCKET' file.

Execution scenarios

The simplest execution scenario involves a single person working on a single computer. There may be a number of caches, representing different projects, but normally the user will work with only one at a time. One client process and one server process will be running whenever the user is actually interacting with Odin.

A slightly more complex situation involves a team, all of whom run on the same machine. Again, the team may be working on several different projects so there may be several caches. More than one member of the team may, however, be working with a particular cache at the same time. In that case, there will be one server process associated with each active cache, and one client process associated with each active user. The server process will mediate all of the client requests on a particular cache to guarantee atomicity. If two clients' requests have products in common, each of those products will only be built once because the server knows that once the product is up-to-date it need not be rebuilt.

Students working on individual projects, using a collection of networked computers with a shared file system, can treat the situation as though they were running on a single machine. A small problem is that if they do not specify a cache explicitly with the -c parameter, they will have a distinct cache on each of the machines they use. In order to avoid this duplication, we advocate use of the ODINVIEW environment variable to define a single default cache name (see Name of the cache).

The most complex scenario is exemplified by students working in teams in a lab with multiple machines and a shared file system. Presumably each team member is sitting at a different machine. One student will start a client, resulting in a server running on that student's machine. Now a second student starts a client on a different machine, but referring to the project's common cache. At that point, one server and two clients are running. The server and one of the clients are both running on the first student's machine, and the other client is running on the second student's machine.

Having clients run on different machines improves performance. Remember that the client is responsible for executing tools that are not built into Odin, so running clients on different machines allows such tools to operate in parallel. Since much of the cost of a given derivation is the cost of running tools, this is an important benefit. Another way of executing tools on different machines is to use a BuildHosts list (see Client execution).

An Odin server makes very heavy use of cache files, many of which are quite small. Experience has shown that there is a serious performance degradation when the server must access the cache over the network. Thus it is useful to run an Odin server on the computer where the files are actually stored. The educational computer laboratory again provides a good example: the shared file system is often stored on a central computer that serves the information to the workstations in the laboratory. One could start a session for the desired cache on the central computer, and simply leave that session open. Subsequent sessions for that cache, started on workstations, would use the server running on the central computer.

Socket implementation

Odin supports two socket implementations: unix internet (AF_INET) sockets and unix domain (AF_UNIX) sockets. The default is AF_INET; AF_UNIX is used only if the environment variable ODIN_LOCALIPC is set to 1.

AF_INET sockets can handle all of our execution scenarios (see Execution scenarios). When the environment involves a file system shared by several machines, however, AF_UNIX sockets can be used if and only if all interactions with a given cache at a given time involve a single machine. This restriction imposes an intolerable burden on a team, because each team member must find out whether a server is already running, and if so which machine it is running on, before they can start their own client. It also makes execution of a server on a central machine and clients on associated workstations impossible. Thus ODIN_LOCALIPC should be set to 1 only if Eli will not function otherwise.

The socket implementation is reflected in two cache files, `SOCKET' and `ENV'. If the socket implementation is AF_UNIX, then `SOCKET' is the actual socket on which the server is listening for client connections rather than a text file (see Interprocess communication).

`ENV' stores the values of important environment variables (including that of ODIN_LOCALIPC) that were in effect at the time that the cache was created or last reset by a -R parameter (see Packages in the cache). Thus a specific socket implementation technique is associated with each cache individually. That technique is used whenever a session begins on the cache; it can be changed only by establishing the appropriate value of ODIN_LOCALIPC and resetting the cache via the -R parameter.

Interprocess communication failures in Eli can occur in two contexts: communication between client and server, and communication between a client and a child running a command. A failure to communicate between client and server almost always results in the error report Cannot connect to Odin server when making the system originally. If there have been no other difficulties (e.g. stopping and restarting the make, re-configuring, etc.), then you should try the following: 

make clean
ODIN_LOCALIPC=1 make

Please report all instances in which setting ODIN_LOCALIPC=1 is necessary to build the system (see Problem Reporting).

If you are able to build the system initially without setting ODIN_LOCALIPC=1, but the report Cannot connect to Odin server appears during normal operation, the problem is almost certainly that the server has been killed before it had the chance to remove file `SOCKET' from the cache. Resetting the cache with either the -r or -R parameter should fix this.

A failure to communicate between a client and a child running a command usually results in the system simply locking up. Lockups could also conceivably occur in the socket communication, so it is important to try to eliminate that possibility. If the parameter -s is given on the eli command line then only a single process, acting as both the client and the server, is used. The program still establishes the `SOCKET' file in the cache, but sockets will remain unused if you don't start any other clients on the same cache. Any lockups that occur in this mode of operation cannot be due to client/server interaction.

If the lockups are intermittent, be certain to make several test runs with the -s command line parameter before concluding that client/server interaction is the culprit.

Previous Chapter Next Chapter Table of Contents