From eb7647ee6ce96fdeb3f49a341463efab50cc7658 Mon Sep 17 00:00:00 2001
From: anand76 <anand76@devvm1373.frc2.facebook.com>
Date: Fri, 24 May 2019 13:24:52 -0700
Subject: [PATCH] Add comments t get_context.h

Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/5353

Differential Revision: D15497912

Pulled By: anand1976

fbshipit-source-id: 72cff2465ca342aa810f925be5a7016b938aa416
---
 table/get_context.h | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/table/get_context.h b/table/get_context.h
index 7ed316f0e..856e01a95 100644
--- a/table/get_context.h
+++ b/table/get_context.h
@@ -17,6 +17,9 @@ namespace rocksdb {
 class MergeContext;
 class PinnedIteratorsManager;
 
+// Data structure for accumulating statistics during a point lookup. At the
+// end of the point lookup, the corresponding ticker stats are updated. This
+// avoids the overhead of frequent ticker stats updates
 struct GetContextStats {
   uint64_t num_cache_hit = 0;
   uint64_t num_cache_index_hit = 0;
@@ -41,8 +44,17 @@ struct GetContextStats {
   uint64_t num_cache_compression_dict_bytes_insert = 0;
 };
 
+// A class to hold context about a point lookup, such as pointer to value
+// slice, key, merge context etc, as well as the current state of the
+// lookup. Any user using GetContext to track the lookup result must call
+// SaveValue() whenever the internal key is found. This can happen
+// repeatedly in case of merge operands. In case the key may exist with
+// high probability, but IO is required to confirm and the user doesn't allow
+// it, MarkKeyMayExist() must be called instead of SaveValue().
 class GetContext {
  public:
+  // Current state of the point lookup. All except kNotFound and kMerge are
+  // terminal states
   enum GetState {
     kNotFound,
     kFound,
@@ -53,6 +65,19 @@ class GetContext {
   };
   GetContextStats get_context_stats_;
 
+  // Constructor
+  // @param value_found If non-nullptr, set to false if key may be present
+  //                    but we can't be certain because we cannot do IO
+  // @param max_covering_tombstone_seq Pointer to highest sequence number of
+  //                    range deletion covering the key. When an internal key
+  //                    is found with smaller sequence number, the lookup
+  //                    terminates
+  // @param seq If non-nullptr, the sequence number of the found key will be
+  //            saved here
+  // @param callback Pointer to ReadCallback to perform additional checks
+  //                 for visibility of a key
+  // @param is_blob_index If non-nullptr, will be used to indicate if a found
+  //                      key is of type blob index
   GetContext(const Comparator* ucmp, const MergeOperator* merge_operator,
              Logger* logger, Statistics* statistics, GetState init_state,
              const Slice& user_key, PinnableSlice* value, bool* value_found,
@@ -64,13 +89,15 @@ class GetContext {
 
   GetContext() = default;
 
+  // This can be called to indicate that a key may be present, but cannot be
+  // confirmed due to IO not allowed
   void MarkKeyMayExist();
 
   // Records this key, value, and any meta-data (such as sequence number and
   // state) into this GetContext.
   //
   // If the parsed_key matches the user key that we are looking for, sets
-  // mathced to true.
+  // matched to true.
   //
   // Returns True if more keys need to be read (due to merges) or
   //         False if the complete value has been found.
@@ -133,6 +160,9 @@ class GetContext {
   bool* is_blob_index_;
 };
 
+// Call this to replay a log and bring the get_context up to date. The replay
+// log must have been created by another GetContext object, whose replay log
+// must have been set by calling GetContext::SetReplayLog().
 void replayGetContextLog(const Slice& replay_log, const Slice& user_key,
                          GetContext* get_context,
                          Cleanable* value_pinner = nullptr);