Work in progress.. Do not read..

High-level overview

Here is a simple diagram that shows the flow of data in the code.

Finding the Right Master

The client first has to find the right master to talk to - the master that holds the required data. To do this, RamCloud::read() invokes ObjectFinder::lookup(). It checks client's tabletMap - which is a cache of coordinator's tablet map. If that tablet is recovering or if the object was not found in any tablet, then the cache is refreshed. This is done by refresher(tabletMap) which is hardwired to CoordinatorClient::getTabletMap in the constructor.

Finally, lookup() returns the SessionRef. SessionRef is a reference to a Session object on which we send client RPC requests. RamCloud::read() uses this to create an instance of the right master and invoking read().

Sending RPC Request

MasterClient::read() creates the RPC Request. The structure for all RPCs is defined in Rpc.h. For Read request, the RPC contains the following fields:

• RpcType type
• uint64_t id
• uint64_t tableId
• uint64_t pad1
• RejectRules rejectRules

Call to sendRecv() sends request over session and later gets response. sendRecv() is defined in Client.h.

Master Processing

<lookup in HT
Data is at fixed offset from SEH
Length is calculated
Forming response Buffer>

On the other hand:

BUFFER contains:

• Transport Layer Header
• Response Header, respHdr (see Rpc.h)
  • For ReadRpc, the Response struct has:
    • version
    • length
    • pad
• Data (obj->data from above diagram)

Client Request Processing

<truncating response>

(TODO: sort / remove)

Other random code-related stuff

RamCloud.cc -> read()

• get SessionRef by objectFinder.lookup(): SessionRef is a reference to a Session object on which we send client RPC requests.
• create an instance of MasterClient - master
• call read on master

MasterClient.cc -> read()

• sendRecv sends request (Rpc - reqHdr, Buffer - req) and gets response (Rpc - respHdr, Buffer - value) over session.
• checkStatus throws any exceptions at that point. HERE (macro) translates to current location in the code (line num and file name).

MasterServer.cc

• When it is running - run() - it is continuously polling for rpcs by:
  • handleRpc<MasterServer>()
• In Server.h, handleRpc<>() is hardwired to call dispatch() amongst doing other things.
• Thus, when an rpc is received:
  • dispatch() -> callHandler<>() -> MasterServer::read()

NOTE about code flow:
When xClient - sendRecv,   ?where x is Coordinator or Master
then xServer - handleRpc<>() -> dispatch() -> callHandler<>() -> ..

Client.h -> sendRecv()

• AsyncState state is created. contains:
  • pointer to responseBuffer
  • rpc
• send (clientSend) requestBuffer and responseBuffer over session.
• wait for it to return (state.rpc->wait())
• return received responseHeader

EndNode: What? Why? How?

What: A simple introduction to understanding how a "read" works in RAMCloud based on my current understanding.

Why: For me to refer to later on, and hopefully to serve as a good starting point to other new comers to RAMCloud system.

How: Information deduced from reading code, and asking lot of silly questions to Diego, Ryan; and a few to Stephen, Nandu and Christian.