Coda File System

(Illustration by Gaich Muramatsu)

• News
• About
• Downloads
• Mailing lists
• Bugs
• FAQ
• Documentation
• Development
• Research
• Wiki

1. Preface

RPC2 is a portable and extensible remote procedure call package built on top of the IP/UDP network protocol. Since its original use in the Andrew File System@cite[Howard88], it has been used by the Coda File System@cite[Satyanarayanan89b], the Scylla database server and a variety of other applications at Carnegie Mellon University and elsewhere. RPC2 runs on LWP, a lightweight process package that allows multiple non-preemptive threads of control to coexist within one Unix process. RP2Gen is a stub generator that simplifies the use of RPC2. RPC2 and LWP run entirely at user-level on the Unix 4.3BSD interface; no kernel changes are necessary.

The first versions of LWP and RPC2 were operational in early 1984 and mid-1985 respectively. The design of LWP predates that of the Cthreads package in Mach@cite[cthreads]. LWP and Cthreads are conceptually similar, but differ substantially in the details. It should, in principle, be possible to modify RPC2 to run directly on top of Cthreads, but we have not tried to do this so far. We have successfully emulated all of LWP on top of the preemptive and nonpre-emptive versions of Cthreads, and a subset of the non-preemptive version of Cthreads on top of LWP.

Both LWP and RPC2 have evolved over time, resulting in increased functionality and robustness. They have also been ported to a wide variety of machine architectures, such as IBM-RTs, MIPS, Sun2, Sun3, Sparc, and i386, as well as variants of the Unix operating systems such as Mach, SunOS and AIX. The RPC2 extensions include the SFTP side effect mechanism for streaming file transfer, the MultiRPC mechanism for parallel RPC calls, and IP multicast versions of MultiRPC and SFTP. Whenever there has been choice between portability and machine-specific performance, we have always favored portability.

Although this manual may seem formidable, RPC2 is not difficult to use. For simple applications you do not have to know everything described in these pages. Advanced features such as use of side effects, MultiRPC, and use of multicast for parallelism can be ignored initially.

Some day there will be a true tutorial in this manual. Until then the best way to learn RPC2 is as follows:

1. Study the overview and examples in Chapter XXX . The latter are actual pieces of working code, and you should try running the examples. Appendix XXX < @@ref > UsageNotesXXX gives you details of library and include file names, current limitations, and other similar details. Read Chapter XXX next. This describes the procedural abstraction provided by RP2Gen, the stub generator.
2. Read Chapter XXX and Part @ref[LWPPart], which describe the RPC2 and LWP runtime calls, respectively. You may need to refer to Appendix XXX < @@ref > HeaderFilesAppendixXXX, which contains the header files used by these packages.
3. After you have mastered the basics, you may wish to explore the advanced features described in Chapters XXX , XXX and XXX .
4. If you wish to learn about the internals of RPC2, you may wish to consult the chapters in Part XXX < @@ref > IntPartXXX.

Credits

The original design, implementation and documentation of RPC2 was by M. Satyanarayanan. The MultiRPC implementation and chapter were done by Ellen Siegel. The extensions to use multicast were done by James Kistler. Jonathan Rosenberg contributed to the RP2Gen implementation and chapter. Comments from Robert Sidebotham, David Nichols, Vasilis Apostolides, Drew Perkins, Bradley White, Stephen Hecht and many other users have been helpful in the improvement of RPC2.

The original design and implementation of LWP was done by Larry Raper. Its documentation descends from a manual by Jonathan Rosenberg and Larry Raper, later extended by David Nichols and M. Satyanarayanan. Richard Draves, Qi Lu, Anders Klemets and Gowthami Rajendran helped in revising and improving this document.

RPC2 User Reference