Merge branch 't/recv_improvements'

[paraslash.git] / buffer_tree.c

diff --git a/buffer_tree.c b/buffer_tree.c
index d92d9863e10e2b4081fba91a35b06233933a15cc..88fb8362bb0c9233d9a5916519b4acf47f4a63ed 100644 (file)
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2010 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2009-2011 Andre Noll <maan@systemlinux.org>
  *
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
@@ -257,6 +257,8 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size)
  *
  * \param bnd Specifies how to create the new node.
  *
+ * \return A pointer to the newly allocated node.
+ *
  * This function always succeeds (or calls exit()). The returned pointer must
  * be freed using btr_free_node() after the node has been removed from the
  * buffer tree via btr_remove_node().
@@ -603,7 +605,7 @@ size_t btr_next_buffer(struct btr_node *btrn, char **bufp)
  *
  * This function must be used to get rid of existing buffer references in the
  * node's input queue. If no references to a buffer remain, the underlying
- * buffers are either freed (in the non-buffer tree case) or the read head of
+ * buffers are either freed (in the non-buffer pool case) or the read head of
  * the buffer pool is being advanced.
  *
  * Note that \a numbytes may be smaller than the buffer size. In this case the
@@ -660,9 +662,15 @@ void btr_consume(struct btr_node *btrn, size_t numbytes)
        return btr_consume(btrn, sz);
 }
 
-static void flush_input_queue(struct btr_node *btrn)
+/**
+ * Clear the input queue of a buffer tree node.
+ *
+ * \param btrn The node whose input queue should be cleared.
+ */
+void btr_drain(struct btr_node *btrn)
 {
        struct btr_buffer_reference *br, *tmp;
+
        FOR_EACH_BUFFER_REF_SAFE(br, tmp, btrn)
                btr_drop_buffer_reference(br);
 }
@@ -670,6 +678,8 @@ static void flush_input_queue(struct btr_node *btrn)
 /**
  * Free all resources allocated by btr_new_node().
  *
+ * \param btrn Pointer to a btr node obtained by \ref btr_new_node().
+ *
  * Like free(3), it is OK to call this with a \p NULL pointer argument.
  */
 void btr_free_node(struct btr_node *btrn)
@@ -700,7 +710,7 @@ void btr_remove_node(struct btr_node *btrn)
        PARA_NOTICE_LOG("removing btr node %s from buffer tree\n", btrn->name);
        FOR_EACH_CHILD(ch, btrn)
                ch->parent = NULL;
-       flush_input_queue(btrn);
+       btr_drain(btrn);
        if (btrn->parent)
                list_del(&btrn->node);
 }
@@ -768,8 +778,8 @@ void btr_splice_out_node(struct btr_node *btrn)
  *
  * \param btrn The node whose output queue size should be computed.
  *
- * This function iterates over all children of the given node and returns the
- * size of the largest input queue.
+ * \return This function iterates over all children of the given node and
+ * returns the size of the largest input queue.
  */
 size_t btr_get_output_queue_size(struct btr_node *btrn)
 {
@@ -824,8 +834,9 @@ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result)
 /**
  * Obtain the context of a buffer node tree.
  *
- * The returned pointer equals the context pointer used at creation time of the
- * node.
+ * \param btrn The node whose output queue size should be computed.
+ *
+ * \return A pointer to the \a context address specified at node creation time.
  *
  * \sa btr_new_node(), struct \ref btr_node_description.
  */