[t:2811], add comments as result of Bradley's CR

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

newbrt/brt.c

@@ -4015,6 +4015,17 @@ brt_cursor_cleanup_dbts(BRT_CURSOR c) {
     }
 }
 
+//
+// This function is used by the leafentry iterators.
+// returns TOKUDB_ACCEPT if live transaction context is allowed to read a value
+// that is written by transaction with LSN of id
+// live transaction context may read value if either id is the root ancestor of context, or if
+// id was committed before context's snapshot was taken.
+// For id to be committed before context's snapshot was taken, the following must be true:
+//  - id < context->snapshot_txnid64 AND id is not in context's live root transaction list
+// For the above to NOT be true:
+//  - id > context->snapshot_txnid64 OR id is in context's live root transaction list
+//
 static
 int does_txn_read_entry(TXNID id, TOKUTXN context) {
     int rval;

newbrt/brttypes.h

@@ -127,6 +127,16 @@ typedef int (*generate_row_for_del_func)(DB *dest_db, DB *src_db, DBT *dest_val,
 typedef struct memarena *MEMARENA;
 typedef struct rollback_log_node *ROLLBACK_LOG_NODE;
 
+//
+// Types of snapshots that can be taken by a tokutxn
+//  - TXN_SNAPSHOT_NONE: means that there is no snapshot. Reads do not use snapshot reads.
+//                       used for SERIALIZABLE and READ UNCOMMITTED
+//  - TXN_SNAPSHOT_ROOT: means that all tokutxns use their root transaction's snapshot
+//                       used for REPEATABLE READ
+//  - TXN_SNAPSHOT_CHILD: means that each child tokutxn creates its own snapshot
+//                        used for READ COMMITTED
+//
+
 typedef enum __TXN_SNAPSHOT_TYPE { 
     TXN_SNAPSHOT_NONE=0,
     TXN_SNAPSHOT_ROOT=1,

newbrt/log-internal.h

@@ -84,8 +84,13 @@ struct tokulogger {
     LSN lsn; // the next available lsn
     OMT live_txns; // a sorted tree.  Old comment said should be a hashtable.  Do we still want that?
     OMT live_root_txns; // a sorted tree.
-    OMT snapshot_txnids;    //contains TXNID pairs (x,y) | x is snapshot txn, y is oldest in its live list
-    OMT live_list_reverse;  //contains TXNID pairs (x,y) | y is oldest txnid s.t. x is in y's live list
+    OMT snapshot_txnids;    //contains TXNID x | x is snapshot txn
+    //contains TXNID pairs (x,y) | y is oldest txnid s.t. x is in y's live list
+    // every TXNID that is in some snapshot's live list is used as the key for this OMT, x, as described above. 
+    // The second half of the pair, y, is the youngest snapshot txnid (that is, has the highest LSN), such that x is in its live list.
+    // So, for example, Say T_800 begins, T_800 commits right after snapshot txn T_1100  begins. Then (800,1100) is in 
+    // this list
+    OMT live_list_reverse;  
     struct logbuf inbuf; // data being accumulated for the write
 
     // To access these, you must have the output condition lock.

newbrt/ule.c

@@ -146,6 +146,10 @@ toku_get_youngest_live_list_txnid_for(TXNID xc, OMT live_list_reverse) {
     return rval;
 }
 
+//
+// This function returns TRUE if live transaction TL1 is allowed to read a value committed by
+// transaction xc, false otherwise.
+//
 static BOOL
 xid_reads_committed_xid(TXNID tl1, TXNID xc, OMT live_list_reverse) {
     BOOL rval;
@@ -219,9 +223,7 @@ garbage_collection(ULE ule, OMT snapshot_xids, OMT live_list_reverse) {
     for (i = 0; i < ule->num_cuxrs; i++) {
         //Shift values to 'delete' garbage values.
         if (necessary[i]) {
-            if (i != first_free) {
-                ule->uxrs[first_free] = ule->uxrs[i];
-            }
+            ule->uxrs[first_free] = ule->uxrs[i];
             first_free++;
         }
     }