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:
make doc
in the RAMCloud directory. Then open the file docs/doxygen/index.html
in a Web browser.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.
You can also invoke any of the RAMCloud RPCs asynchronously, and it is relatively straightforward to manage multiple simultaneous outstanding RPCs.
RAMCloud::CreateTableRpc
corresponding to the createTable
method.RAMCloud::CreateTableRpc
; the constructor arguments are the same as those for the synchronous method such as createTable. C
onstructing the Rpc object initiates the RPC, but does not wait for it to complete.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)wait
method on an asynchronous Rpc object, the RAMCloud poller will automatically be invoked. However, if your program only calls isReady
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();
isReady
method on an Rpc object from time to time to ensure that the RPC "makes progress". Certain actions, such as retrying RPCs after server failures, are invoked only from within isReady
.isReady
has returned true for an RPC, you should call wait
to complete the RPC. At this point, wait
is guaranteed not to block. There are two reasons for calling wait
. First, this is the only way to get any results returned by the RPC. Second, if the RPC completed with an error condition, this is the only way to find out about that error: wait
may throw exceptions, but isReady
never throws any exceptions.