This page contains basic information on how to write client applications that use the RAMCloud storage system.
API documentation
For information on the APIs available to client applications, consult the RAMCloud doxygen docs, which are generated from the RAMCloud source code. There are two ways you can access the doxygen docs:
- Generate the latest version from your RAMCloud sources by typing
make doc
in the RAMCloud directory. Then open the filedocs/doxygen/index.html
in a Web browser. - Use the precompiled doxygen docs available from our Web site.
The doxygen documentation covers the entire source base, most of which is internal RAMCloud classes that are not useful to application writers. The primary API documentation for client applications is that for the class RAMCloud::RamCloud
(click on the Classes
tab at the top of the main page, then search down for the link to RAMCloud::RamCloud
). There is one method in this class for each RPC supported by RAMCloud. These methods invoke RPCs synchronously: for example, the createTable
method will not return until the operation has completed and a response has been received from the coordinator.
Invoking RPCs asynchronously
You can also invoke any of the RAMCloud RPCs asynchronously, and it is relatively straightforward to manage multiple simultaneous outstanding RPCs.
- There is a separate class corresponding to each RPC, whose name derives naturally from the name of the corresponding method in RAMCloud::RamCloud. For example, there is a class
RAMCloud::CreateTableRpc
corresponding to thecreateTable
method. - To invoke an RPC asynchronously, construct the corresponding Rpc object such as
RAMCloud::CreateTableRpc
; the constructor arguments are the same as those for the arguments for the synchronous method such ascreateTable. C
onstructing the Rpc object initiates the RPC, but does not wait for it to complete. - Objects such as
RAMCloud::CreateTableRpc
support the following methods:wait
: waits synchronously for the RPC to completeisReady
: tests whether the RPC has completed, without blockingcancel
: aborts the RPC (deleting the object also has this effect)
- Note: RAMCloud RPCs are implemented using a polling approach. This means that asynchronous RPCs will not make progress or complete unless you occasionally invoke the RAMCloud polling mechanism. If you invoke a synchronous RPC, or if you call the
wait
method on asynchronous Rpc object, the RAMCloud poller will automatically be invoked. However, if your program only callsisReady
to test for completion, then you must also occasionally invoke the RAMCloud poller. If you have created a RamCloud object named rc, the following statement will invoke the poller:rc.clientContext->dispatch->poll();
An example application
The file src/ClientMain.cc
in the RAMCloud source directory contains a simple RAMCloud application. Here are a few general hints about writing applications:
- The main include file you will need is
RamCloud.h
, which is in the RAMCloud source directory. This file also includes many other RAMCloud include files. - To open a connection with the cluster, you create a
RAMCloud::RamCloud
object. The arguments to the constructor provide information about how to connect with the cluster; these are typically the same as command-line options passed to the cluster coordinator when it was started. - Once you have a
RamCloud
object, you can use its methods to invoke RAMCloud operations.
How to compile an application
Here is an example command for compiling a RAMCloud client application:
g++ -Lobj.master -lramcloud -Isrc -Iobj.master -o TestClient TestClient.cc
This assumes the following:
- The application is in the file TestClient.cc, which is in the top-level RAMCloud directory.
- RAMCloud itself has already been compiled.
- The RAMCloud sources are using the master git branch.
If the application is in a different directory, or if the RAMCloud sources are not using the master branch, you will need to adjust the command line accordingly.