Project 2 - Simple RPC

See the assignment turn-in page (last modified on 9 February 2004) for instructions on turning in your assignment.

A single sRPC server implements a single service, which consists of one or more calls. Clients of a particular sRPC server can make any of the calls supported by the server. For example, an sRPC server implementing the dictionary service described in Chapter 23 of Comer and Stevens would support the calls initialize(), insert(), delete(), and lookup(), and quit().

An sRPC service call is similar to a normal subroutine or method call, except that an sRPC service call is more limited in the types of parameters it can use. An sRPC service-call parameter can be an integer, a string, or an array. An integer is a signed, 32-bit value. An sRPC string is a sequence of zero or more eight-bit characters (The ISO 8859-1 characters, also known as the Latin-1 characters); an sRPC string is not zero terminated. An sRPC array is a sequence of zero or more values of the array's base type. sRPC arrays are dynamic; they have no fixed maximum size. sRPC Arrays are also recursive; an array's base type may also be an array.

In left to right order, the components of the system are:

• User supplied client code: The code that accesses sRPC services via the service calls implemented by the service. This code is supplied by the sRPC user.

• sRPC client interface code: The code that supplies the service calls used by the client code. This code is generated by the sRPC system; the code generator is provided by the sRPC implementor (that's you).

• sRPC client-side run-time system: The code responsible for making the sRPC service calls on behalf of the client. This code is supplied by the sRPC implementor (that's you)

• sRPC protocol: However it is that the sRPC client and server run-times decide to communicate. This protocol is designed and implemented by the sRPC implementor (that's you).

• sRPC server-side run-time: The code responsible for handing off the incoming service calls to the server code and returning the results to the client. This code is provided by the sRPC implementor (that's you).

• sRPC server interface code: The routines called by the sRPC server-side run-time in response to incoming service calls. This code is generated by sRPC; the code generator is designed an implemented by the sRPC implementor (that's you).

• User supplied server code: The code that implements the service calls provided by this service. This code is provided by the sRPC user.

Although the diagram shows a single client, an sRPC server can handle multiple clients.

The sRPC run-time system is responsible for implementing all sRPC functions, including data marshaling, data transmission, and sRPC system-call semantics. There is a separate run-time system for the client and server sides, but the run-time systems can (and should) share much infrastructure code.

The sRPC run-time system is generic with respect to the services it supports; the same run-time system works with all possible services defined in sRPC. The srpc-gen interface-code generator is responsible for creating the code that bridges the gap between the specific requirements of a particular service and the generic facilities of the sRPC run-time system.

A service-description file is a text file with a simple format: a service name spec followed by one or more service-call specs. A service-name spec is a single line starting with the text service followed by an identifier giving the name of the service:

For example, the service-description file for the Dictionary service might start with

service Dictionary

Following the service-name spec is one or more service-call specs. A service-call spec consists of a call-name spec followed by zero or more call-parameter specs. A call-name spec is a single line starting with the text call followed by an identifier giving the name of the call:

Each call identifier must be unique among all call identifiers in the same specification file.

Each call-parameter spec is a single line of text consisting of a direction, a type spec, and an identifier:

The direction dir is either in or out and indicates if the parameter is an input (in) or output (out) parameter. type-spec indicates the parameter's type; type-spec can be one of int for an integer, string for a string, or array of type-spec for an array containing values of the given type. ident is the parameter's name; the identifier must be unique among all parameter names in the same service-call spec; parameter names may be repeated in different service-call specs.

For example, this service-call spec

call insert
in  string word
out int    inserted
out string emsg

describes the Dictionary service's insert call.

1. setup a local endpoint for an sRPC service and establish a connection to a remote sRPC server for the service.

   call setup
   in string  hostname
   in int     port_number
   out string emsg
   

   port_number is in host-byte order. The sRPC server is located at hostname:port_number. This must be the first service call made by a client. If emsg is empty after a call to setup(), no error occurred during the call; otherwise, emsg contains an error description.

2. determine the service calls offered by the sRPC server.

   call query
   out string spec
   out string emsg
   

   After the call to query(), spec contains the server's service-description file and emsg contains an error indicator as described above.

3. shutdown the connection to the remote sRPC server and reclaim the resources allocated to the local endpoint.

   call shutdown
   out string emsg
   

   emsg contains an error indicator as described above. Once shutdown() is called for a particular endpoint, any other sRPC calls to that endpoint are invalid.

   A call to shutdown() effects only the associated endpoint; any other endpoints to the same sRPC server, and any other endpoints to other sRPC servers, remain unchanged.

   The server-side generic service calls allow a server to

   1. initialize the server at the start of service.

      call initialize
      out string emsg
      

      emsg contains an error indicator as described above. initialize() is called once by the sRPC run-time code at the start of execution to initialize the implementor-supplied server code.

   2. shut-down the server code in preparation for stopping the server.

      call shutdown
      out string emsg
      

      emsg contains an error indicator as described above. shutdown() is called once by the sRPC run-time coded at the end of server execution.

   Notice that the server interface does not include the query() generic sRPC service call.

The specifics of binding sRPC depend on the host language. There are sRPC language bindings for C++ and Java; the bindings for other host languages will be similar to these two bindings. Keep in mind that these are example bindings; if you don't like these, you're free to make your own.

1. Write srpc-gen.

2. Write the sRPC run-time system, including the sRPC protocol.

service Dictionary

Then would follow a sequence of service calls describing the interface to the Dictionary server:

call insert
in  string word
out int    inserted
out string emsg

call delete
in  string word
out string emsg

call lookup
in  string word
out int    found
out string emsg

call quit
out string emsg

Assuming this service-description file is named dictionary.srpc and that srpc-gen produces C++ code, running dictionary.srpc through srpc-gen produces the four files dictionary-client.h, dictionary-client.cc, dictionary-server.h, and dictionary-server.cc.