refs #5198, add comments documenting client contract

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

ft/txn_manager.cc

@@ -690,6 +690,17 @@ void toku_txn_manager_note_commit_txn(TXN_MANAGER txn_manager, TOKUTXN txn) {
     return;
 }
 
+//
+// This function is called only via env_txn_xa_recover and env_txn_recover.
+// See comments for those functions to understand assumptions that 
+// can be made when calling this function. Namely, that the system is 
+// quiescant, in that we are right after recovery and before user operations
+// commence.
+//
+// I (Zardosht), don't think we take advantage of this fact, as we are holding
+// the txn_manager_lock in this function, but in the future we might want
+// to take these assumptions into account.
+//
 int toku_txn_manager_recover_txn (
     TXN_MANAGER txn_manager, 
     struct tokulogger_preplist preplist[/*count*/], 

src/ydb.cc

@@ -1449,6 +1449,13 @@ env_txn_stat(DB_ENV * env, DB_TXN_STAT ** UU(statp), uint32_t UU(flags)) {
     return 1;
 }
 
+//
+// We can assume the client calls this function right after recovery 
+// to return a list of prepared transactions to the user. When called,
+// we can assume that no other work is being done in the system, 
+// as we are in the state of being after recovery, 
+// but before client operations should commence
+//
 static int
 env_txn_xa_recover (DB_ENV *env, TOKU_XA_XID xids[/*count*/], long count, /*out*/ long *retp, uint32_t flags) {
     struct tokulogger_preplist *MALLOC_N(count,preps);
@@ -1463,6 +1470,13 @@ env_txn_xa_recover (DB_ENV *env, TOKU_XA_XID xids[/*count*/], long count, /*out*
     return r;
 }
 
+//
+// We can assume the client calls this function right after recovery 
+// to return a list of prepared transactions to the user. When called,
+// we can assume that no other work is being done in the system, 
+// as we are in the state of being after recovery, 
+// but before client operations should commence
+//
 static int
 env_txn_recover (DB_ENV *env, DB_PREPLIST preplist[/*count*/], long count, /*out*/ long *retp, uint32_t flags) {
     struct tokulogger_preplist *MALLOC_N(count,preps);