[btr]: Minor documentation improvements.
authorAndre Noll <maan@systemlinux.org>
Mon, 28 Dec 2009 20:13:57 +0000 (21:13 +0100)
committerAndre Noll <maan@systemlinux.org>
Mon, 28 Dec 2009 20:13:57 +0000 (21:13 +0100)
buffer_tree.c

index bbd055b..9a59fff 100644 (file)
@@ -36,7 +36,7 @@ struct btr_node {
        struct list_head input_queue;
 };
 
-#define FOR_EACH_TARGET_NODE(_tn, _btrn) list_for_each_entry((_tn), \
+#define FOR_EACH_CHILD(_tn, _btrn) list_for_each_entry((_tn), \
        &((_btrn)->children), node)
 
 #define FOR_EACH_BUFFER_REF(_br, _btrn) \
@@ -59,6 +59,11 @@ struct btr_node *btr_new_node(char *name, struct btr_node *parent)
        return btrn;
 }
 
+/*
+ * Allocate a new btr buffer.
+ *
+ * The freshly allocated buffer will have a zero refcount.
+ */
 static struct btr_buffer *new_btrb(char *buf, size_t size)
 {
        struct btr_buffer *btrb = para_malloc(sizeof(*btrb));
@@ -69,6 +74,9 @@ static struct btr_buffer *new_btrb(char *buf, size_t size)
        return btrb;
 }
 
+/*
+ * Deallocate the reference, release the resources if refcount drops to zero.
+ */
 void btr_drop_buffer_reference(struct btr_buffer_reference *br)
 {
        struct btr_buffer *btrb = br->btrb;
@@ -82,15 +90,15 @@ void btr_drop_buffer_reference(struct btr_buffer_reference *br)
        }
 }
 
-static void add_btrb_to_targets(struct btr_buffer *btrb, struct btr_node *btrn)
+static void add_btrb_to_children(struct btr_buffer *btrb, struct btr_node *btrn)
 {
-       struct btr_node *tn; /* target node */
+       struct btr_node *ch;
 
-       FOR_EACH_TARGET_NODE(tn, btrn) {
+       FOR_EACH_CHILD(ch, btrn) {
                struct btr_buffer_reference *br = para_malloc(sizeof(*br));
                br->btrb = btrb;
                br->consumed = 0;
-               list_add_tail(&br->node, &tn->input_queue);
+               list_add_tail(&br->node, &ch->input_queue);
                btrb->refcount++;
        }
 }
@@ -100,12 +108,12 @@ void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
        struct btr_buffer *btrb;
 
        btrb = new_btrb(buf, size);
-       add_btrb_to_targets(btrb, btrn);
+       add_btrb_to_children(btrb, btrn);
 }
 
 void btr_pushdown_br(struct btr_buffer_reference *br, struct btr_node *btrn)
 {
-       add_btrb_to_targets(br->btrb, btrn);
+       add_btrb_to_children(br->btrb, btrn);
        btr_drop_buffer_reference(br);
 }
 
@@ -117,7 +125,8 @@ void btr_pushdown(struct btr_node *btrn)
                btr_pushdown_br(br, btrn);
 }
 
-bool btr_no_children(struct btr_node *btrn)
+/* Return true if this node has no children. */
+bool btr_is_leaf_node(struct btr_node *btrn)
 {
        return list_empty(&btrn->children);
 }
@@ -168,10 +177,10 @@ static void flush_input_queue(struct btr_node *btrn)
 
 void btr_del_node(struct btr_node *btrn)
 {
-       struct btr_node *tn;
+       struct btr_node *ch;
 
-       FOR_EACH_TARGET_NODE(tn, btrn)
-               tn->parent = NULL;
+       FOR_EACH_CHILD(ch, btrn)
+               ch->parent = NULL;
        flush_input_queue(btrn);
        if (btrn->parent)
                list_del(&btrn->node);