[t:4240] starting to comment brt-flusher.h brt-cachetable-wrappers.h

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

newbrt/brt-cachetable-wrappers.c

@@ -121,12 +121,6 @@ toku_create_new_brtnode (
         NULL);
 }
 
-//
-// The intent of toku_pin_brtnode(_holding_lock) is to abstract the process of retrieving a node from
-// the rest of brt.c, so that there is only one place where we need to worry applying ancestor
-// messages to a leaf node. The idea is for all of brt.c (search, splits, merges, flushes, etc)
-// to access a node via toku_pin_brtnode(_holding_lock)
-//
 int
 toku_pin_brtnode(
     BRT brt,
@@ -170,7 +164,6 @@ toku_pin_brtnode(
     return r;
 }
 
-// see comments for toku_pin_brtnode
 void
 toku_pin_brtnode_holding_lock(
     BRT brt,
@@ -280,7 +273,6 @@ checkpoint_nodes(struct brt_header* h,
 
 void
 toku_unpin_brtnode_off_client_thread(struct brt_header* h, BRTNODE node)
-// Effect: Unpin a brt node.
 {
     int r = toku_cachetable_unpin(
         h->cf,
@@ -294,7 +286,6 @@ toku_unpin_brtnode_off_client_thread(struct brt_header* h, BRTNODE node)
 
 void
 toku_unpin_brtnode(BRT brt, BRTNODE node)
-// Effect: Unpin a brt node.
 {
     // printf("%*sUnpin %ld\n", 8-node->height, "", node->thisnodename.b);
     VERIFY_NODE(brt,node);

newbrt/brt-cachetable-wrappers.h

@@ -11,6 +11,9 @@
 
 C_BEGIN
 
+/**
+ *
+ */
 void
 cachetable_put_empty_node_with_dep_nodes(
     struct brt_header* h,
@@ -21,6 +24,9 @@ cachetable_put_empty_node_with_dep_nodes(
     BRTNODE* result
     );
 
+/**
+ *
+ */
 void
 create_new_brtnode_with_dep_nodes(
     struct brt_header* h,
@@ -31,6 +37,9 @@ create_new_brtnode_with_dep_nodes(
     BRTNODE* dependent_nodes
     );
 
+/**
+ *
+ */
 void
 toku_create_new_brtnode (
     BRT t,
@@ -39,17 +48,9 @@ toku_create_new_brtnode (
     int n_children
     );
 
-void
-toku_pin_brtnode_off_client_thread(
-    struct brt_header* h,
-    BLOCKNUM blocknum,
-    u_int32_t fullhash,
-    BRTNODE_FETCH_EXTRA bfe,
-    u_int32_t num_dependent_nodes,
-    BRTNODE* dependent_nodes,
-    BRTNODE *node_p
-    );
-
+/**
+ *
+ */
 void
 checkpoint_nodes(
     struct brt_header* h,
@@ -57,6 +58,13 @@ checkpoint_nodes(
     BRTNODE* dependent_nodes
     );
 
+/**
+ * The intent of toku_pin_brtnode(_holding_lock) is to abstract the
+ * process of retrieving a node from the rest of brt.c, so that there is
+ * only one place where we need to worry applying ancestor messages to a
+ * leaf node. The idea is for all of brt.c (search, splits, merges,
+ * flushes, etc) to access a node via toku_pin_brtnode(_holding_lock)
+ */
 int
 toku_pin_brtnode(
     BRT brt,
@@ -70,6 +78,9 @@ toku_pin_brtnode(
     BRTNODE *node_p
     ) __attribute__((__warn_unused_result__));
 
+/**
+ * see comments for toku_pin_brtnode
+ */
 void
 toku_pin_brtnode_holding_lock(
     BRT brt,
@@ -82,9 +93,29 @@ toku_pin_brtnode_holding_lock(
     BRTNODE *node_p
     );
 
+/**
+ *
+ */
+void
+toku_pin_brtnode_off_client_thread(
+    struct brt_header* h,
+    BLOCKNUM blocknum,
+    u_int32_t fullhash,
+    BRTNODE_FETCH_EXTRA bfe,
+    u_int32_t num_dependent_nodes,
+    BRTNODE* dependent_nodes,
+    BRTNODE *node_p
+    );
+
+/**
+ * Effect: Unpin a brt node.
+ */
 void
 toku_unpin_brtnode_off_client_thread(struct brt_header* h, BRTNODE node);
 
+/**
+ * Effect: Unpin a brt node.
+ */
 void
 toku_unpin_brtnode(BRT brt, BRTNODE node);
 

newbrt/brt-flusher.c

@@ -380,12 +380,6 @@ brtleaf_split(
     BOOL create_new_node,
     u_int32_t num_dependent_nodes,
     BRTNODE* dependent_nodes)
-// Effect: Split a leaf node.
-// Argument "node" is node to be split.
-// Upon return:
-//   nodea and nodeb point to new nodes that result from split of "node"
-//   nodea is the left node that results from the split
-//   splitk is the right-most key of nodea
 {
 
     //    printf("###### brtleaf_split():  create_new_node = %d, num_dependent_nodes = %d\n", create_new_node, num_dependent_nodes);
@@ -585,12 +579,6 @@ brt_nonleaf_split(
     DBT *splitk,
     u_int32_t num_dependent_nodes,
     BRTNODE* dependent_nodes)
-// Effect: node must be a node-leaf node.  It is split into two nodes, and the fanout is split between them.
-//    Sets splitk->data pointer to a malloc'd value
-//    Sets nodea, and nodeb to the two new nodes.
-//    The caller must replace the old node with the two new nodes.
-//    This function will definitely reduce the number of children for the node,
-//    but it does not guarantee that the resulting nodes are smaller than nodesize.
 {
     //VERIFY_NODE(t,node);
     toku_assert_entire_node_in_memory(node);

newbrt/brt-flusher.h

@@ -11,12 +11,26 @@
 
 C_BEGIN
 
+/**
+ * Only for testing, not for production.
+ *
+ * Set a callback the flusher thread will use to signal various points
+ * during its execution.
+ */
 void
 toku_flusher_thread_set_callback(
     void (*callback_f)(int, void*),
     void* extra
     );
 
+/**
+ * Brings the node into memory and flushes the fullest buffer.  If the
+ * heaviest child is empty, does nothing, otherwise, executes
+ * flush_some_child to do the flush.
+ *
+ * Wrapped by toku_brtnode_cleaner_callback to provide access to
+ * brt_status which currently just lives in brt.c.
+ */
 int
 toku_brtnode_cleaner_callback_internal(
     void *brtnode_pv,
@@ -26,6 +40,10 @@ toku_brtnode_cleaner_callback_internal(
     BRT_STATUS brt_status
     );
 
+/**
+ * Puts a workitem on the flusher thread queue, scheduling the node to be
+ * flushed by flush_some_child.
+ */
 void
 flush_node_on_background_thread(
     BRT brt,
@@ -33,6 +51,14 @@ flush_node_on_background_thread(
     BRT_STATUS brt_status
     );
 
+/**
+ * Effect: Split a leaf node.
+ * Argument "node" is node to be split.
+ * Upon return:
+ *   nodea and nodeb point to new nodes that result from split of "node"
+ *   nodea is the left node that results from the split
+ *   splitk is the right-most key of nodea
+ */
 void
 brtleaf_split(
     struct brt_header* h,
@@ -45,6 +71,15 @@ brtleaf_split(
     BRTNODE* dependent_nodes
     );
 
+/**
+ * Effect: node must be a node-leaf node.  It is split into two nodes, and
+ *         the fanout is split between them.
+ *    Sets splitk->data pointer to a malloc'd value
+ *    Sets nodea, and nodeb to the two new nodes.
+ *    The caller must replace the old node with the two new nodes.
+ *    This function will definitely reduce the number of children for the node,
+ *    but it does not guarantee that the resulting nodes are smaller than nodesize.
+ */
 void
 brt_nonleaf_split(
     struct brt_header* h,