[t:3945], add some comments

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

newbrt/brt.c

@@ -1533,6 +1533,15 @@ brtleaf_split (BRT t, BRTNODE node, BRTNODE *nodea, BRTNODE *nodeb, DBT *splitk,
     if (create_new_node) {
         // put value in cachetable and do checkpointing
         // of dependent nodes
+        //
+        // We do this here, before evaluating the split_node
+        // and split_at_in_node because this operation
+        // may write to disk the dependent nodes.
+        // While doing so, we may rebalance the leaf node
+        // we are splitting, thereby invalidating the
+        // values of split_node and split_at_in_node.
+        // So, we must call this before evaluating
+        // those two values
         cachetable_put_empty_node_with_dep_nodes(
             t,
             num_dependent_nodes,

newbrt/cachetable.c

@@ -1530,6 +1530,8 @@ note_hash_count (int count) {
 }
 
 // has ct locked on entry
+// This function MUST NOT release and reacquire the cachetable lock
+// Its callers (toku_cachetable_put_with_dep_pairs) depend on this behavior.
 static int cachetable_put_internal(
     CACHEFILE cachefile, 
     CACHEKEY key, 
@@ -1706,6 +1708,19 @@ int toku_cachetable_put_with_dep_pairs(
     //
     CACHETABLE ct = cachefile->cachetable;
     cachetable_lock(ct);
+    //
+    // The reason we call cachetable_wait_write outside 
+    // of cachetable_put_internal is that we want the operations
+    // get_key_and_fullhash and cachetable_put_internal
+    // to be atomic and NOT release the cachetable lock.
+    // If the cachetable lock is released within cachetable_put_internal,
+    // we may end up with a checkpoint beginning that has 
+    // called get_key_and_fullhash (which causes a blocknum
+    // to be allocated) but without the PAIR being in the cachetable
+    // and checkpointed. The checkpoint would have a leaked blocknum.
+    // So, we call cachetable_wait_write outside, and ensure that 
+    // cachetable_put_internal does not release the cachetable lock
+    //
     cachetable_wait_write(ct);
     get_key_and_fullhash(key, fullhash, get_key_and_fullhash_extra);
     int r = cachetable_put_internal(