The Remote Procedure Call packagec(635)\b4f5 21f0 8B
Henry Thompsone12c
File:	{ivy}<hthompson>lisp>rpc>rpc.bravo, .press
Revised:	January 23, 1983  12:19 AMe12\f1 84f0
Remote Procedure Callse12j\ub22UB
The file <lispusers>rpc.dcom implements the (documentation forthcoming - ref. Andrew Birrell) Cedar RPC transport mechanism.  Its architecture is copied more or less directly from the Cedar implementation, to which reference should be made in difficulty.  It is designed to be used in conjunction with stubs produced by the Interlisp-D version of Lupine (see below) to provide remote service.e12j\9f8 19f0
To start the RPC world, call InitRPC() - to turn it off, use StopRPC().e12j\29f8 9f0 23f8 10f0
LUPINE - Producing stubse12j\ub1f1 8f0 15UB
The goal of all this is to allow an Interlisp-D system to export services to or import services from remote machines.  The file <lispusers>lupine.dcom implements a stub creation mechanism modeled on the Cedar version (ref. Bruce Nelson's thesis (CSL-81-9) and the Lupine User's Guide - [indigo]<cedar>documentation>LupineUsersGuide.press.).  In particular the function Lupine(packageName functionSpecList signalSpecList lupineTypeString) will produce a set of server stubs to interface between the RPC transport mechanisms and a set of vanilla Lisp functions, and a set of client stubs to communicate between callers of those functions and the RPC transpost mechanism.  This allows the network to intervene between the caller and the callee.  e12j\128f8 22f0 219f8 68f0
The crucial point to comprehend in the RPC world is that the semantics of a remote call are the same as the semantics of a local call - all the effort is directed at hiding the fact that anything out of the ordinary is going on - pay no attention to the man behind the curtain.e12j
A trivial example will demonstrate the basic story - suppose we have the following Cedar interface spec:e12j
Trivial: DEFINITIONS =

BEGIN
Trivial: PROC[arg1: INT, arg2: Rope.ROPE] RETURNS[result: BOOLEAN];

TrivialFailure: TYPE = { badNum, badString };

TrivialFailed: SIGNAL[why: TrivialFailure];

END.e12\f8 195f0
Translating this with Cedar Lupine will produce client and server interfaces to the RPC transport mechanisms.  To plug into those with from Lisp, or to plug Lisp to Lisp, we must supply the same information as is contained in the Cedar interface spec. to Lisp.  The following records from Lisp Lupine are used to specify an interface:e12
(RECORD FunctionSpec (fn args result resultArg))
(RECORD ArgSpec (argName argType argParm))
(RECORD ResultSpec (resRecord . resBits))
(RECORD ResBit (resField resType resParm))e12\f8 176f0
The following are the equivalent for Lisp Lupine of the above interface spec:e12j
(RPAQQ TrivialSpec (
	(Trivial ((arg1 FIXP)(arg2 STRING)) BOOLEAN)  ))
(RPAQQ TrivialSignals (
	(TrivialFailed ENUMERATION (badNum badString) NIL)  ))e12\f8 150f0
The same format is used for both functions and signals, since signals are just functions by another name.  Signals are described in <lispusers>signal.press.e12j\132f8 23f0
The types available are {SSMALLP FIXP BOOLEAN STRING ATOM STREAM ENUMERATION}, where SSMALLP is -215 - 215-1, and STREAM is like string but goes directly onto a stream.  The equivalent Cedar types are {INTEGER INT BOOLEAN Rope.ROPE ATOM Rope.ROPE <enumerated type>}.  On the Lisp side, the latter two types take and additional specification - the name of the stream to use in the STREAM case, and the set of values in the ENUMERATION case.e12j\23f8 1f0 1f8 51f0 9f8 7f0 6o4 2o0 4o4 2o0 8f8 6f0 81f8 64f0 115f8 6f0 36f8 11f0
The syntax of the spec is confused by the necessity for distinguishing single from multiple return values, and atomic from compound arguments to signals.  Thus the result field may either have a complex specification, giving the record name and field specifications for unpicking a multiple return, or it may simply give the type of a single return.  In the latter case, the resultArg field is used for the parameter of the type, if any.  This option of single vs. multiple is present for both the args and result fields of a signal spec, as the function Signal itself has only one parameter for the argument(s) to the signal being raised, so if this parameter is compound it too must have a record for unpicking and/or constructing it.  This leads to the following additional complexity, that if the single argument to a signal requires a parameter, then the rest of the spec. is displaced to make room for it.  This is shown in the example above, where the single argument is an enumerated type.  The NIL is the result spec. - any one of function arg, signal arg, function result, or signal result may be NIL.e12j\164f6 6f0 205f6 9f0 114f6 4f0 5f6 6f0 44f6 4f0 442f6 3f0
If we call (Lupine 'Trivial TrivialSpec TrivialSignals "magic-string") we will get back the names of a pair of filecoms for all the necessary stubs etc.  The magic-string will be used as a default in the process of matching server and client at the time of initial connection.  If you want to allow it to default to the same value as the default generated by Cedar Lupine, you can read it out of the file TrivialRpcClientImpl.mesa, at the point in the definition of ImportInterface where it says:e12j\11f8 60f0 87i12I235f8 25f0 36f8 15f0
type:  IF ~IsNull[type]
	THEN type ELSE "magic-string"L,l4269e12j\f8 56f0
To actually export the interface so that clients can call you, you must create an instance of the record InterfaceName, with the field instance set to the name of the service you wish to provide, which should be a Grapevine rName.  Then you can call ExportTrivial(<the InterfaceName> <user> <password>), where the user and password are owners of the rName in the interface.  Likewise to import an interface exported by someone else, use ImportTrivial(<the InterfaceName>).  See the forthcoming Cedar RPC documentation for a discussion of all the options with respect to establishing connections.e12j\105f8 13f0 17f8 8f0 107f8 52f0 135f8 35f0
A complete example is the easiest way to understand how all this works.  {ivy}<hthompson>lisp>rpc>simple and ...>simpleuser are the basis for such an example.  The functions in simpleuser call the functions in simple.  simple contains the necessary arguments for Lupine.  ...>simpleclient and ...>simpleserver contain the stubs generated by Lupine.  simpleuser and simpleclient would be loaded into one machine, and simple and simpleserver into another.   {ivy}<hthompson>cedar>rpc>simple.df is a directory of all the Cedar files needed to make up the equivalent server and/or client in Cedar.e12j\73f8 32f0 4f6 14f0 54f6 10f0 23f6 6f0 3f6 6f0 38f6 6f0 3f6 16f0 5f6 16f0 32f6 6f0 3f6 11f0 3f6 13f0 39f6 6f0 5f6 12f0 17f8 35f0
Messages to HThompson.pae12j\12f8 12f0