Lupine is the translator for Cedar's [Cedar] remote procedure call mechanism. A thorough understanding of remote procedure call (RPC) principles is assumed throughout this guideindeed, once-skeptical readers have assured us it is foolish to continue without adequate background. Nelson's dissertation [RPC] provides more than the necessary foundation, as Lupine, not surprisingly, resembles that thesis's Emissary mechanism closely (Lupine, however, includes no orphan algorithms). Be particularly conversant with chapters 1 and 2, and section 5.4.

Xerox's Office Products Division has its own RPC mechanism, Courier [CourierFS, CourierPS]. Courier is for use in standard Pilot [Pilot] environments and has its own Lupine-like translator, Diplomat [Diplomat]. The Courier system is supported by OPD and is released with Pilot; it is the product software RPC mechanism. Lupine, in contrast, is supported by CSL for use primarily within CSL and PARC. Lupine's remote calls execute in both the Cedar and Pilot environments, are about ten times faster than Courier's, and are significantly easier to program.

Lupine reads a compiled Mesa interface and mechanically writes four Mesa source modules that implement the same interface remotely. For a given DEFINITIONS interface named Target, Lupine's stub control interface and three stub modules are:

Appendix B contains an example of each of these generated modules. As you use this guide, refer to appendix B as necessary for concrete examples.

To use the stub modules compiled from the generated programs, clients include them in configurations on their client and server hosts. Aside from these configuration modifications, the only required program changes are two procedure calls to routines in TargetRpcControl. These binding calls, discussed in detail later, cause the serving machine to export Target and the client machine to import it. This scenario is slightly more complicated with secure calls or multiple instantiation, and much more complicated with dynamic crash recovery.

To establish bindings, make secure calls, and handle exceptions, Cedar RPC programmers use an RPCRuntime package interface called RPC. There is a parallel interface, MesaRPC, for standard Pilot programmers. Appendix A reproduces both of these interfaces.

Cedar's RPC mechanism is the work of two people: Andrew Birrell designed and wrote the RPCRuntime package with its transport, binding, and secure communication subsystems; Bruce Nelson designed the stub format and wrote the Lupine translator and diagnostic tools. In addition, members of the Alpine and Voice projectsMark Brown, Dan Swinehart, and Ed Taft, in particularmade numerous good suggestions about parameter marshaling and multiple interface instances. Dan was also a revealing alpha tester.

This guide is primarily Nelson's venture, with Birrell contributing material on secure communication and remote binding.

The Lupine translator runs in the Cedar environment (but a Tajo version would be trivial if needed). To install Lupine and all the necessary RPCRuntime underpinnings, use Bringover to retrieve the public components of [Indigo]<Cedar>Top>Lupine.df.

Lupine reads the BCD of a compiled interface and writes four output files. At present, Lupine is used from the Executive, although eventually it will be under the control of the Cedar system modeller. Establishing a command file to translate each remote interface, or package of interfaces, is recommended for now.

The basic procedure is this:

Lupine records its translation progress in the Executive's window and log. The source and object files for the stubs will be many times larger than the original interface, so be sure you have sufficient space for them.

To abort a translation just click "STOP!" in the CommandTool window.

Lupine can be invoked from the command line or used interactively from the keyboard. There is one real command, TranslateInterface, and a number of option-setting commands. They are presented here in procedural keyboard style. Consult a Lupine wizard before using a nondefault value for DefaultParameterPassing, FreeServerArguments or DynamicHeapNews.

There are additional debugging commands for wizards only. Type ? at any point for a list of possible commands or responses.

The following example illustrates option-setting and translation in command files:

Fortunately, because Lupine's input is compiler output, few translation errors are possible. Most errors are caused by parameter passing restrictions. Lupine reports errors both in the typescript and in the output file itself. Error and warning messages in the typescript include the output file name and character position of the error, and messages in the output file are preceded with "#####" to make them easy to spot. Many errors cause an ERROR statement to be inserted in the output file. This prevents a bogus stub from executing when the result would be chaos. If you can't understand a particular error message, see a Lupine wizard.

As mentioned above, if a set of stubs is too big to compile, the InlineDispatcherStubs option may remedy the problem.

The compiler will occasionally issue warning messages about referenced but unused DIRECTORY items as it compiles stub programs. Lupine is a mechanical translator, and eliminating the spurious warnings would be difficult. Live with them.

The compiler may give errors like "must come from an imported interface" or "is an unmatched implicit import". Edit the IMPORTS statement in the program to overcome this.

Translated interfaces tend to be quite large. If you overflow the compiler, try translating with the options above that trade space for speed.

Lupine and the RPC runtime provide facilities for making secure remote calls. Such calls are encrypted using the DES encryption algorithm [DES]. The protocols used provide secure two-way authentication without any passwords being passed in the clear [Needham-Schroeder]. Secure RPC calls prevent an intruder from seeing the procedure names, parameters, or results of the calls; from modifying calls in transit; from replaying previously valid calls; from observing passwords (encryption keys) in transit; from observing the cipher text of known (or chosen) plain text.

Secure RPC communication is based on the concept of a conversation. A conversation takes place between two authenticated Grapevine individuals, known as the originator and the responder of the conversation.

A conversation is created by the originator calling RPC.StartConversation and is destroyed by the originator calling RPC.EndConversation. The originator provides his own name and password and the name of the responder. StartConversation communicates with Grapevine to verify the validity of these arguments; at this time there is no communication with the responder. See below for a description of the SecurityLevel of a conversation. At present, the communication with Grapevine does not use secure protocols.

Having created the conversation, the originator may now make secure calls to the responder by passing the Conversation as the first argument of any remote call to a procedure in an interface that is exported by the responder. (The same conversation may be used to make calls in multiple interfaces.) The RPC runtime guarantees that the call can be understood only inside a host containing the authenticated responder and that the call will be received by the responder at most once. The responder can determine the authenticated identity of the originator by calling RPC.GetCaller when he receives a call having the Conversation as its first argument. Every conversation is uniquely identified for all time by an identifier that either party may obtain by calling RPC.GetConversationID. Calling RPC.StartConversation may raise the exception AuthenticateFailed, with the following values for its argument:

The procedure GenerateConversation may be called to obtain a Conversation to be used solely for calls within a single machine; such a Conversation must not be used for remote calls.

The SecurityLevel passed to StartConversation indicates how much security the originator wants for this conversation. The SecurityLevel of any conversation may be obtained by calling GetLevel. The meanings of the conversation levels are as follows. none indicates that the conversation was created by calling GenerateConversation, and that no authentication or encryption has been employed. authOnly will perform the authentication, but calls are not encrypted, and modification, manufacture or replay of calls or results is not detected. ECB uses the ECB mode of DES [DES], which protects calls and results from eavesdropping (and makes modifying, manufacturing or replaying calls or results somewhat more difficult). ECB mode does not hide patterns of repeated data within or between calls. CBC uses the CBC mode of DES [DES],, which behaves like ECB except that it hides repeated data patterns. CBCCheck is like CBC, with the addition of a checksum on each call and result; this prevents any eavesdropping, modification, manufacture or replay of a call or result. CBCCheck should normally be used for secure communication, and authOnly should normally be used for applications where only authantication is desired; the other values of SecurityLevel are advisable only where hardware or performance constraints dictate. At present the DES algorithm is replaced by a trivial exclusive-or algorithm, because of the absence of encryption hardware.

Lupine does not perform remote binding by using remote versions of the modeller or C/Mesa binder [Mesa]. Instead, the modeller or binder are used to bindlocallyto an instance of TargetRpcControl. A remote interface, say Target, is then bound remotely by calling binding procedures in the TargetRpcControl interface. These procedures use the RPCRuntime, in cooperation with Grapevine [Grapevine], to perform remote binding. This is elaborated below, after a discussion of remote interface naming.

Naming remote interfaces is much more complicated than naming local-machine interfaces because remote interfaces must be uniquely identifiable in a distributed environment. Furthermore, ability to control the degree of typechecking is required for widespread systems such as Laurel (see sections 4.1.3.1 and 4.1.3.4 in Nelson's thesis [RPC]). Lupine addresses this problem with InterfaceNames, defined below. (ShortROPEs are discussed in the Parameter Passing section.)

For interface Target, calling TargetRpcControl.ExportInterface causes Target (as specified by interfaceName) to be exported for immediate remote use. Any attempts to import Target before ExportInterface completes, or after UnexportInterface completes, will raise an exception (see the description of importing, below). These two routines must be called in the strict sequence ExportInterface, UnexportInterface, ExportInterface, .... Calling UnexportInterface has no effect on calls in progress.

The precise behavior of ExportInterface depends on the value of interfaceName. If the interfaceName.instance is a Grapevine R-Name, the Grapevine registration service is consulted to ensure that the instance is an individual whose connect-site is a Pup net address for the exporting machine. If necessary, the database is updated, using the given user and password as credentials. If the instance is not an R-Name (that is, it does not contain a dot), it should be either a Pup Name Lookup Server name that maps to the exporting machine, or a Pup net address constant for the exporting machine. If the interfaceName.type is an R-Name, the Grapevine database is consulted (and updated if necessary) to ensure that the type is a group, one of whose members is the interfaceName.instance. At present, these actions on an interfaceName.type which is an R-Name are not implemented; every type is treated as just a string.

If you call ExportInterface and default the interfaceName.type, Lupine will use for the type a combination of the interface name (for example, "Target") and the compiler's version stamp for the interface. The default type is thus a unique name for the remote interface, and this uniqueness permits the default version to be matchAllVersions  of which there can be just one.

Calling ExportInterface with a defaulted interfaceName.instance is not yet supported; exporters and importers must give an explicit instance each time. For simple experiments, it is convenient to use your own Grapevine R-Name as the instance, and your own credentials as parameters to ExportInterface. For example:

If an attempt to export a remote interface fails, the exception ExportFailed is raised. No monitors are locked when this signal is raised, so further calls into the RPC runtime may be made from catch-phrases. The parameter of the signal is one of the following:

Remote importing of an interface Target may be caused by calling TargetRPCControl.ImportInterface or TargetRPCControl.ImportNewInterface, as described below. In either case, an interfaceName is provided, which is interpreted as follows.

If interfaceName.instance is not NIL, then it must be: a Grapevine R-Name that is an individual whose connect-site is a Pup net address, a Pup Name Lookup server host name, or a Pup net address constant. Each of these maps to a net address of a machine, which is assumed to be the machine that has previously exported the desired interface. If that machine is running the Cedar RPC package and has exported an interface whose InterfaceName has the same type and instance, and whose version is compatible with the importer's interfaceName.version, then the import succeeds and the importer's stub is now bound to the exporter's stub.

If interfaceName.instance is NIL, then the remote binder will attempt to find any exported interface whose type and version match those given in interfaceName. If the type is a Grapevine R-Name, then it should specify a Grapevine group. The binder enumerates the members of that group, obtains the network addresses that are the connect-sites of the members, and tries to bind to them in turn until one succeeds. The order of these binding attempts is undefined, but is closely related to hop-count and responsiveness. The algorithm usually chooses the nearest instance of the type that is operational. If the type is a Pup Name Lookup server name string, then this algorithm is performed with the network addresses that are the value of that name. Importing with interfaceName.instance = NIL is not yet implemented.

If an attempt to import a remote interface fails, the ERROR ImportFailed is raised. No monitors are locked when this signal is raised, so further calls into the RPC runtime may be made from catch-phrases. The parameter of the signal is one of the following:

For interface Target, calling TargetRpcControl.ImportInterface causes Target (as specified by interfaceName) to be remotely imported for immediate use. In the C/Mesa sense, Target was bound when TargetRpcClientImpl, which exports Target locally, was bound. But remote binding is not complete until ImportInterface is called. As a consequence, any attempts to use operations in Target before ImportInterface completes, or after UnimportInterface completes, will fail unrecoverably. Calling UnimportInterface has no effect on calls in progress. These two routines should normally be called in the strict sequence ImportInterface, UnimportInterface, ImportInterface, .... However, calling ImportInterface without an intervening call to UnimportInterface will just remotely import the interface as if UnimportInterface had been called. Note that ImportInterface[someInterface] will raise the exception RPC.ImportFailed[unbound] unless some host has previously called ExportInterface[someInterface].

For interface Target, calling TargetRpcControl.ImportNewInterface causes a new instance of Target (as specified by interfaceName) to be created and remotely imported for immediate use. Typically, each call of ImportNewInterface will specify a different value for interfaceName.instance, thus binding to a different, distributed instance of the Target interface. The operations in this new instance must be accessed through the interfaceRecord that ImportNewInterface returns, not through Target itself, as in the static importing case discussed above. (The Target interface is useless to RPC programmers using multiple instances and should not even be referenced.) For example, if Target contains procedure WritePages, a call to WritePages must be written interfaceRecord.WritePages[...], not Target.WritePages[...]. Any attempts to use operations in interfaceRecord before ImportNewInterface completes, or after UnimportNewInterface completes, will fail unrecoverably. Calling UnimportNewInterface has no effect on calls in progress. UnimportNewInterface is available only for the Mesa target environment. In Cedar, discarded remote interfaces are garbage collected. Note that
ImportNewInterface[someInterface] will fail unless some host has previously called ExportInterface[someInterface].

When a distributed program deals with multiple remote instances, it is often true that one (or more) of the instances will actually reside on the local host. In this case, performing remote calls to the local instance can have an undesirable performance impact. RPC programmers who want to optimize "remote" calls to local dynamic instances can do so in the following fashion:

To unmarshal certain parameters, Lupine's stubs must allocate private storage. This storage is taken from zones that RPC programmers can specify at binding time. For simple interfaces a set of standard zones is adequate, and thus the binding operations have default standardZones (below). For production interfaces that use address-containing (AC) parameters frequently, however, establishing special-purpose zones can increase performance significantly. If a remote interface uses a large number of small AC objects (except for ropes, which get special treatment from the Rope package), or it uses any large AC objects, consult a Lupine wizard.

The compile-time relationships of Target modules, Lupine's stub modules, and the RPCRuntime packages are shown below. If module B is to the right of module A, then B depends on A.

As a general rule, Lupine.df exports all the Lupine, LupineRuntime, RPCRuntime, and Cedar runtime components needed by remote programs. Thus DF files describing remote applications should say [Exports] Imports Lupine.df to get all required components, although tailoring with a USING list may be worthwhile.

Remote calls typically take place between independent hosts, and thus, for a given Target interface, Target's client and implementation modules, along with the necessary stubs, must be split between the cooperating hosts. A simple division of the Target service into remote TargetClient and TargetServer C/Mesa configurations is illustrated below. Constructing corresponding Cedar models would be similar.

The purpose of the user-written ClientRpcImportImpl and ServerRpcExportImpl modules is to import and export the remote Target interface by making calls on TargetRpcControl's Import(New)Interface and ExportInterface routines. These trivial binding operations could just as well be placed in TargetClientImpl and TargetImpl, or combined with the binding operations of other remote interfaces into one master binding module. Note that these configurations do not include the RPC runtime package, RPCRuntime.bcd. This package should normally be loaded separately, because it is essential that only one copy of this package is loaded into any machine. Check with current Cedar release documentation to see whether RPCRuntime.bcd is included in the Cedar boot file.

It is sometimes advantageous to have both client and server configurations loaded into one host, as for single-machine debugging. Such configurations must be specified cautiously, however, so that remote imports and exports are not misconnected locally, short circuiting all remote calls. The easiest way to do this is to use nested configurations, as in the following example.

These TargetClient and TargetServer examples are simple; more elaborate configurations will be commonly required. See appendix A of the Diplomat document [Diplomat] for further, more complicated, examples, or consult a Lupine wizard.

A general discussion of crashes and crash recovery in the context of RPC is outside the scope of this guide. The main reason is insufficient experience with distributed systems: there is no widespread agreement on an RPC-level crash recovery methodology, or, indeed, if such a methodology is even needed or possible at this level. In currently operational distributed systems, those with the best crash behavior appear to use highly application-specific techniques. See Nelson's thesis [RPC] for more discussion (sections 4.1.1, 4.2.3, 5.1, 7.2).

Lupine's RPCRuntime uses the RPC.CallFailed exception to report crashes and other remote call execution problems. This exception can be reported by any invocation of a remote procedure, or on any signal of a remote signal or error. RPC programmers interested in continuous service must therefore be prepared to catch CallFailed on each remote operation. Recovery actions usually consist of restoring some invariants before trying to rebind to another instance of the remote interface. No monitors are locked when RPC.CallFailed is raised, so further calls into the RPC runtime may be made from catch-phrases. The parameter of the signal is one of the following:

For parameters that do not contain addresses, Lupine's parameter passing semantics are exactly those of Cedar and Mesa: call-by-value. For address-containing (AC) parameters, however, Lupine has four passing semantics: for arguments, VAR, VALUE, RESULT, and HANDLE; for results, just VALUE. Each of these is a copy semantics; Lupine does not support reference semantics (call-by-reference) between disjoint address spaces. Here is a brief description of each; the next secion has examples:

The specification of parameter passing semantics is somewhat awkward because Mesa and Cedar support only call-by-value semantics. There are two methods:

The following table indicates which passing methods are applicable to each type (a blank entry means No). Value semantics is the default in all cases. Further restrictions are listed below.

Lupine's typechecking is no stronger than the compiler's. In generating code, Lupine assumes that the value of a parameter is always a legal value for a parameter of that typethere is no special checking. If a client programmer passes a REF which has been loopholed to an invalid address, or passes an out-of-bounds enumerated or subrange value, the results are unspecified. For example, if Lupine must dereference the bogus REF during marshaling, either an address fault will occur or an equally bogus referent will be handed to an unsuspecting server. For an invalid enumerated or subrange value, a fault will occur only if the stub modules were compiled with bounds checking enabled.

The upshot is that RPC programmers must be just as suspicious of invalid parameters as they would be in the absence of RPC. Furthermore, programmers of servers must be especially careful because RPC client code need not be generated by Lupine, or even written in Mesa.

Lupine tries hard to make local and remote procedure semantics identical, and as a result there are very few restrictions. Here are the details.