[t:4557], add comments from code review of query code

git-svn-id: file:///svn/toku/tokudb@40169 c7de825b-a66e-492c-adef-691d508d4ae1

newbrt/brt-internal.h

@@ -351,7 +351,7 @@ struct brt_header {
     struct brt_header * checkpoint_header;
     CACHEFILE cf;
     // lock used by a thread to pin the root node to start a descent into 
-    // the tree. This lock protects the blocknum of the root node. Any 
+    // the tree. This lock protects the blocknum of the root node (root_blocknum). Any 
     // thread that wants to descend down the tree starting at the root 
     // must grab this lock before pinning the root.
     toku_pthread_mutex_t tree_lock; 
@@ -377,6 +377,7 @@ struct brt_header {
     int64_t num_blocks_to_upgrade_14;   // Number of v14 blocks still not newest version. 
     unsigned int nodesize;
     unsigned int basementnodesize;
+    // this field is protected by tree_lock, see comment for tree_lock
     BLOCKNUM root_blocknum;            // roots of the dictionary
     unsigned int flags;
     DESCRIPTOR_S descriptor;

newbrt/cachetable.c

@@ -2223,7 +2223,9 @@ int toku_cachetable_get_and_pin_with_dep_pairs (
             nb_mutex_write_lock(&p->nb_mutex, ct->mutex);
             pair_touch(p);
             // used for shortcutting a path to getting the user the data
-            // helps scalability for in-memory workloads
+            // helps scalability for in-memory workloads by not holding the cachetable lock
+            // when calling pf_req_callback, and if possible, returns the PAIR to the user without
+            // reacquiring the cachetable lock
             BOOL fast_checkpointing = (resolve_checkpointing_fast(p) && num_dependent_pairs == 0);
             if (p->checkpoint_pending && fast_checkpointing) write_locked_pair_for_checkpoint(ct, p);
             cachetable_unlock(ct);
@@ -2525,6 +2527,10 @@ int toku_cachetable_get_and_pin_nonblocking (
                     write_locked_pair_for_checkpoint(ct, p);
                 }
                 pair_touch(p);
+                // release the cachetable lock before calling pf_req_callback
+                // helps scalability for in-memory workloads by not holding the cachetable lock
+                // when calling pf_req_callback, and if possible, returns the PAIR to the user without
+                // reacquiring the cachetable lock
                 cachetable_unlock(ct);
                 BOOL partial_fetch_required = pf_req_callback(p->value,read_extraargs);
                 //