[btr] Documentation update.
authorAndre Noll <maan@systemlinux.org>
Sun, 17 Jan 2010 12:27:46 +0000 (13:27 +0100)
committerAndre Noll <maan@systemlinux.org>
Sun, 17 Jan 2010 12:27:46 +0000 (13:27 +0100)
buffer_tree.c
buffer_tree.h
stat.c

index 9862a4f..a5b1fd2 100644 (file)
@@ -17,16 +17,12 @@ struct btr_pool {
        char *whead;
 };
 
-enum btr_buffer_flags {
-       /* changes the way the buffer is deallocated */
-       BTR_BF_BTR_POOL = 1,
-};
-
 struct btr_buffer {
        char *buf;
        size_t size;
        /** The number of references to this buffer. */
        int refcount;
+       /* NULL means no buffer pool but a malloced buffer. */
        struct btr_pool *pool;
 };
 
@@ -118,6 +114,18 @@ size_t btr_pool_filled(struct btr_pool *btrp)
        return btr_pool_size(btrp) - (btrp->rhead - btrp->whead);
 }
 
+/**
+ * Get the number of unused bytes in the buffer pool.
+ *
+ * \param btrp The pool.
+ *
+ * \return The number of bytes that can currently be allocated.
+ *
+ * Note that in general the returned number of bytes is not available as a
+ * single contiguous buffer. Use btr_pool_available() to obtain the length of
+ * the largest contiguous buffer that can currently be allocated from the
+ * buffer pool.
+ */
 size_t btr_pool_unused(struct btr_pool *btrp)
 {
        return btr_pool_size(btrp) - btr_pool_filled(btrp);
@@ -209,6 +217,15 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size)
 #define FOR_EACH_BUFFER_REF_SAFE(_br, _tmp, _btrn) \
        list_for_each_entry_safe((_br), (_tmp), &(_btrn)->input_queue, node)
 
+/**
+ * Create a new buffer tree node.
+ *
+ * \param bnd Specifies how to create the new node.
+ *
+ * This function always succeeds (or calls exit()). The returned pointer
+ * must be freed using btr_free_node() after it has been removed from
+ * the buffer tree via btr_remove_node().
+ */
 struct btr_node *btr_new_node(struct btr_node_description *bnd)
 {
        struct btr_node *btrn = para_malloc(sizeof(*btrn));
@@ -312,6 +329,20 @@ static void add_btrb_to_children(struct btr_buffer *btrb,
        }
 }
 
+/**
+ * Insert a malloced buffer into the buffer tree.
+ *
+ * \param buf The buffer to insert.
+ * \param size The size of \a buf in bytes.
+ * \param btrn Position in the buffer tree to create the output.
+ *
+ * This creates references to \a buf and adds these references to each child of
+ * \a btrn. The buffer will be freed using standard free() once no buffer tree
+ * node is referencing it any more.
+ *
+ * Note that this function must not be used if \a buf was obtained from a
+ * buffer pool. Use btr_add_output_pool() in this case.
+ */
 void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
 {
        struct btr_buffer *btrb;
@@ -326,10 +357,16 @@ void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
 }
 
 /**
- * Feed data to child nodes of the buffer tree.
+ * Feed data to child nodes of a buffer tree node.
  *
  * \param btrp The buffer pool.
- * 
+ * \param size The number of bytes to be allocated and fed to each child.
+ * \param btrn The node whose children are to be fed.
+ *
+ * This function allocates the amount of bytes from the buffer pool area,
+ * starting at the current value of the write head, and creates buffer
+ * references to the resulting part of the buffer pool area, one for each child
+ * of \a btrn. The references are then fed into the input queue of each child.
  */
 void btr_add_output_pool(struct btr_pool *btrp, size_t size,
                struct btr_node *btrn)
@@ -406,12 +443,28 @@ int btr_pushdown_one(struct btr_node *btrn)
        return 1;
 }
 
-/* Return true if this node has no children. */
-bool btr_no_children(struct btr_node *btrn)
+/*
+ * Find out whether a node is a leaf node.
+ *
+ * \param btrn The node to check.
+ *
+ * \return True if this node has no children. False otherwise.
+ */
+static bool btr_no_children(struct btr_node *btrn)
 {
        return list_empty(&btrn->children);
 }
 
+/**
+ * Find out whether a node is an orphan node.
+ *
+ * \param btrn The buffer tree node.
+ *
+ * \return True if \a btrn has no parent.
+ *
+ * This function will always return true for the root node.  However in case
+ * nodes have been removed from the tree, other nodes may become orphans too.
+ */
 bool btr_no_parent(struct btr_node *btrn)
 {
        return !btrn->parent;
@@ -437,7 +490,13 @@ size_t btr_get_buffer_by_reference(struct btr_buffer_reference *br, char **buf)
 }
 
 /**
- * \return zero if the input buffer queue is empty.
+ * Obtain the next buffer of the input queue of a buffer tree node.
+ *
+ * \param btrn The node whose input queue is to be queried.
+ * \param bufp Result pointer.
+ *
+ * \return The number of bytes that can be read from buf. Zero if the input
+ * buffer queue is empty. In this case the value of \a bufp is undefined.
  */
 size_t btr_next_buffer(struct btr_node *btrn, char **bufp)
 {
@@ -465,6 +524,21 @@ size_t btr_next_buffer(struct btr_node *btrn, char **bufp)
        return rv;
 }
 
+/**
+ * Deallocate the given number of bytes from the input queue.
+ *
+ * \param btrn The buffer tree node.
+ * \param numbytes The number of bytes to be deallocated.
+ *
+ * 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
+ * the buffer pool is being advanced.
+ *
+ * Note that \a numbytes may be smaller than the buffer size. In this case the
+ * buffer is not deallocated and subsequent calls to btr_next_buffer() return
+ * the remaining part of the buffer.
+ */
 void btr_consume(struct btr_node *btrn, size_t numbytes)
 {
        struct btr_buffer_reference *br, *tmp;
@@ -492,16 +566,14 @@ void btr_consume(struct btr_node *btrn, size_t numbytes)
                assert(true);
        }
        /*
-
-       We have a wrap buffer, consume from it. If in total,
-       i.e. including previous calls to brt_consume(), less than
-       wrap_count has been consumed, there's nothing more we can do.
-
-       Otherwise we drop the wrap buffer and consume from subsequent
-       buffers of the input queue the correct amount of bytes. This
-       is the total number of bytes that have been consumed from the
-       wrap buffer.
-*/
+        * We have a wrap buffer, consume from it. If in total, i.e. including
+        * previous calls to brt_consume(), less than wrap_count has been
+        * consumed, there's nothing more we can do.
+        *
+        * Otherwise we drop the wrap buffer and consume from subsequent
+        * buffers of the input queue the correct amount of bytes. This is the
+        * total number of bytes that have been consumed from the wrap buffer.
+        */
        PARA_DEBUG_LOG("consuming %zu/%zu bytes from wrap buffer\n", numbytes,
                br_available_bytes(br));
 
@@ -546,6 +618,17 @@ void btr_remove_node(struct btr_node *btrn)
                list_del(&btrn->node);
 }
 
+/**
+ * Return the amount of available input bytes of a buffer tree node.
+ *
+ * \param btrn The node whose input size should be computed.
+ *
+ * \return The total number of bytes available in the node's input
+ * queue.
+ *
+ * This simply iterates over all buffer references in the input queue and
+ * returns the sum of the sizes of all references.
+ */
 size_t btr_get_input_queue_size(struct btr_node *btrn)
 {
        struct btr_buffer_reference *br;
@@ -587,7 +670,7 @@ void btr_splice_out_node(struct btr_node *btrn)
  *
  * Iterates over all children of the given node.
  */
-size_t btr_bytes_pending(struct btr_node *btrn)
+static size_t btr_bytes_pending(struct btr_node *btrn)
 {
        size_t max_size = 0;
        struct btr_node *ch;
@@ -608,6 +691,9 @@ int btr_exec(struct btr_node *btrn, const char *command, char **value_result)
        return btrn->execute(btrn, command, value_result);
 }
 
+/**
+ * Execute a inter-node command.
+ */
 int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result)
 {
        int ret;
index 0bb31b1..157c17c 100644 (file)
@@ -1,18 +1,19 @@
 /**
- * Buffer trees and buffer tree nodes.
+ * \file buffer_tree.h Buffer tree management.
  *
+ * \par Buffer trees and buffer tree nodes.
  * The buffer tree API offers a more powerful method than standard unix pipes
  * for managing the data flow from the producer of the data (e.g. the network
  * receiver) to its consumer(s) (e.g. a sound card).
  *
- * Each data buffer starts its way from the root of the buffer tree. At each
- * child node the data is investigated and new data is fed to each child.
- * Everything happens within one single-treaded process. There are no file
- * descriptors, no calls to read() or write().
- *
  * A buffer tree consists of buffer tree nodes linked via certain parent/child
  * relationships.
  *
+ * Each data buffer starts its way from the root of the buffer tree. At each
+ * node the data is investigated and possibly changed. New data is then fed to
+ * each child.  Everything happens within one single-treaded process. There are
+ * no file descriptors and no calls to read() or write().
+ *
  * Whenever a node in the buffer tree creates output, either by creating a new
  * buffer or by pushing down buffers received from its parent, references to
  * that buffer are created for all children of the node. The buffer tree code
  * For example, in para_audiod the alsa writer asks all parent nodes
  * for for the number of channels and the sample rate of the current
  * audio file.
- */
-struct btr_node;
-
-/**
+ *
  * Buffer pools - An alternative to malloc/free buffer management.
  *
  * Non-leaf nodes usually create output to be processed by their children.  The
@@ -37,21 +35,21 @@ struct btr_node;
  * btr_add_output(). This adds references to that buffer to all children. The
  * buffer is automatically freed if no buffer tree node is using it any more.
  *
- * This approach, while simple, has some drawbacks, especially affecting the
- * root nodes of the buffer tree. Often the data source which is represented by
- * a root node does not know in advance how much data will be available.
- * Therefore the allocated buffer is either larger than what can currently be
- * read, or is too small so that multiple buffers have to be used.
+ * This approach, while being simple, has some drawbacks, especially affecting
+ * the root nodes of the buffer tree. Often the data source which is
+ * represented by a root node does not know in advance how much data will be
+ * available.  Therefore the allocated buffer is either larger than what can
+ * currently be read, or is too small so that multiple buffers have to be used.
  *
  * While this could be worked around by using a large buffer and calling
  * realloc() afterwards to shrink the buffer according to how much has been
  * read, there is a second problem which comes from the alignment constraints
- * of some filters, mainly the decoders. These need a minimal amount of data to
- * proceed, and most of them even need this amount as one contiguous buffer,
- * i.e.  not spread out over two or more buffers.
+ * of some filters, mainly the decoders like mp3dec. These need a minimal
+ * amount of data to proceed, and most of them even need this amount as one
+ * contiguous buffer, i.e. not spread out over two or more buffers.
  *
  * Although the buffer tree code handles this case just fine, it can be
- * expensive because two or more buffers must be combined by copying buffer
+ * expensive because two or more buffers must be merged by copying buffer
  * contents around in order to satisfy the constraint.
  *
  * This is where buffer pools come into play. Buffer pools try to satisfy
@@ -70,7 +68,7 @@ struct btr_node;
  * Child nodes consume data by working through their input queue, which is a
  * list of buffer references. Once the content of a buffer is no longer needed
  * by a child node, the child calls btr_consume() to indicate the amount of
- * data which can be dropped from the child's point of view.  If no reference
+ * data which can be dropped from the child's point of view. If no reference
  * to some region of the buffer pool area remains, the read head of the buffer
  * pool advances, making space available for the receiver node to fill.
  *
@@ -81,6 +79,8 @@ struct btr_node;
  * remaining part of the area only. This only happens when the end of the area
  * is reached.
  */
+
+struct btr_node;
 struct btr_pool;
 
 /**
@@ -178,13 +178,10 @@ struct btr_node *btr_new_node(struct btr_node_description *bnd);
 void btr_remove_node(struct btr_node *btrn);
 void btr_free_node(struct btr_node *btrn);
 void btr_add_output(char *buf, size_t size, struct btr_node *btrn);
-bool btr_no_children(struct btr_node *btrn);
-size_t btr_bytes_pending(struct btr_node *btrn);
 size_t btr_get_input_queue_size(struct btr_node *btrn);
 bool btr_no_parent(struct btr_node *btrn);
 size_t btr_next_buffer(struct btr_node *btrn, char **bufp);
 void btr_consume(struct btr_node *btrn, size_t numbytes);
-int btr_exec(struct btr_node *btrn, const char *command, char **value_result);
 int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result);
 void btr_splice_out_node(struct btr_node *btrn);
 void btr_pushdown(struct btr_node *btrn);
diff --git a/stat.c b/stat.c
index 27ffab5..3369091 100644 (file)
--- a/stat.c
+++ b/stat.c
@@ -27,7 +27,7 @@
  * \param item_handler Function to call for each complete item.
  *
  * \return Negative on errors, the number of bytes _not_ passed to \a
- * item_handler.
+ * item_handler on success.
  *
  * Status items are expected in the format used by parser-friendly output mode
  * of the stat command of para_client/para_audioc.