miniRPC: A TCP Remote Procedure Call Library

0.3.3

About miniRPC

miniRPC is a remote procedure call library which works on top of TCP and other stream-oriented transports. It has the following design goals:

• Simple on-the-wire protocol
• Scalability to large numbers of connections
• Automatic stub generation
• No use of a portmapper: clients connect directly to the well-known port for a service
• Simple usage model for synchronous RPCs
• Straightforward support for asynchronous RPCs, including out-of-order replies, at both client and server
• Application-defined event loop
• Support for bidirectional communication: both the client and the server can initiate RPCs
• Support for event notifications, which do not require a reply
• Support for multi-threaded operation with an application-defined threading model
• Support for multiple RPC protocols and protocol roles in a single process
• Support for TLS encryption (currently unimplemented)

miniRPC Terminology

• A miniRPC connection is a single network connection between two endpoints which carries miniRPC traffic.

• The server is the host which listens for incoming connections. The client is the host which initiates a connection to a server.

• The sender of an RPC is the party which initiates an RPC or transmits an event message. The receiver is the party which receives the message and (if applicable) sends a reply.

• A protocol is an application-specific set of remote procedures and data structures which define communication on the wire. miniRPC is a framework for implementing these protocols. The XDR serialization format used by miniRPC is not self-describing, so both parties to a miniRPC connection need to know the protocol being used.

• Every protocol has two protocol roles: client and server. These define the reponsibilities of a particular connection endpoint. For example, a particular connection might be a foo client: a client using the foo protocol.

• A connection set is a container for connections which provides infrastructure (for example, event handling) and some shared configuration values. All connections in a connection set must have the same protocol role. Each connection is associated with exactly one connection set.

• Synchronous RPC calls are those which block until the RPC is complete. Sender-asynchronous calls are those in which the sender does not block; it is notified via a callback function when the RPC reply is received. Receiver-asynchronous calls are those where the receiver's event handler returns before the call has been completely processed; the receiver transmits its reply at a later time using a stub function provided for that purpose. An RPC can be both sender- and receiver-asynchronous. Note that these are properties of the implementation; the on-the-wire format does not distinguish between synchronous and asynchronous RPCs.

Structure of the miniRPC Library

Applications using miniRPC interact with three different interfaces. minirpcgen is the stub generator for miniRPC; it reads a description of the application-specific protocol, and generates C structures and functions corresponding to the protocol definition. The C files generated by minirpcgen implement the protocol-dependent portion of the miniRPC interface, and must be compiled into the client and server applications. miniRPC also provides a protocol-independent interface for common tasks such as library initialization, connection setup and teardown, and event handling.