This tutorial explains, through the use of an example client-server system, how to write a value-added server (VAS) and client programs using the Shore Storage Manager (SSM) programming interface.
This tutorial illustrates many aspects of writing a VAS, including
For a general introduction, see An Overview of Shore or The Shore Storage Manager Programming Interface. See The Shore Release for an index to the rest of the documentation.
We assume you are already familiar with RPC programming. If not we recommend the book Power Programming with RPC, by John Bloomer, published by O'Reilly & Associates, Inc.
The example used throughout this tutorial is a client-server system called grid that illustrates many aspects of building a value-added server and a corresponding client.
The grid example is a simple client-server database system for items located on a 2-dimensional grid. Items have a string name and coordinates on the grid. Multiple items can reside at any location, but each item has a unique name.
The server uses the SSM to manage the grid database. The server implements several update and query commands. Update commands on the grid include adding items, removing items and clearing the grid (removing all items). Query commands on the grid including printing the entire grid, looking up items by name, and locating all items within a rectangular region of the grid. There are also commands for committing and aborting transactions. The server accepts commands from standard input and processes remote procedure calls (RPCs) from multiple clients.
The client accepts commands from standard input and sends them to the server with remote procedure calls (RPCs).
The grid data file and indices are stored on a single volume. The items are stored, one per record, in an SSM file. Each record contains a name and a location. A B+-tree index maps item names to the IDs of the corresponding item records. This index is used to lookup items by name. An R*-tree index maps location coordinates to item records. This index is used to locate all items within a rectangular region of the grid.
The grid server is a multi-threaded threaded program that manages connections from multiple clients and also monitors the terminal (standard input) for commands. The server starts a separate thread for each of these tasks to demonstrate how to use SSM's thread package. Shared state among the threads is protected using the synchronization mechanisms provided by the thread package.
The client and server use the SSM's configuration options package to read configuration information from configuration files and the program command line arguments.
This example does not demonstrate all of the features of the SSM. In particular, it does not demonstrate
Most of the unused features are used in the Shore VAS (see src/vas) and the Paradise database system (see http://www.cs.wisc.edu/paradise/ ). Almost every feature is also tested by the SSM testing program ssh, located in src/sm/ssh.
This tutorial walks through the example program sources in detail. The sources, as well as associated test programs and data, may be found in the examples/vas/grid sub-directory of the distribution.
The rest of this tutorial is organized as follows. The following two sections present the storage structures and operations on them. The next two sections discuss how to implement servers and clients. The final two sections explain how to compile and run the example. An Appendix contains a listing of the code.