For New Developers - Understanding Reads in RAMCloud

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..

TODO: Chritian's diagram here (fig 3 from his report). Edit to make corrections.

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)