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.

Now that we have that out of the way..

Follow the code and read along..

Code Flow:

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

This is an edited version of the figure originally made by Cristian (thanks for sharing!)

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
xServer - handleRpc<>() -> dispatch() -> callHandler<>() -> ..

ObjectFinder.cc -> lookup()

• check client's tabletMap (which is a cache of coordinator's tablet map)
• if that tablet is recovering or if the obj was not found in any tablet:
  • refresh that cache by:
  • refresher(tabletMap) - hardwired to CoordinatorClient::getTabletMap (in the constructor)
• finally return the SessionRef

Some general information:

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)