audiod cleanups.

[paraslash.git] / buffer_tree.c

diff --git a/buffer_tree.c b/buffer_tree.c
index 1ea68917cd5438cffc4d64a5d3292d43fcd7da3a..9862a4f150b040ddaa1ce2b3b8f842520a52032a 100644 (file)
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -8,6 +8,7 @@
 #include "error.h"
 #include "sched.h"
 
+/* whead = NULL means area full */
 struct btr_pool {
        char *name;
        char *area_start;
@@ -56,6 +57,17 @@ struct btr_node {
        void *context;
 };
 
+/**
+ * Create a new buffer pool.
+ *
+ * \param name The name of the new buffer pool.
+ *
+ * \param area The size in bytes of the pool area.
+ *
+ * \return An opaque pointer to the newly created buffer pool. It must be
+ * passed to btr_pool_free() after it is no longer used to deallocate all
+ * resources.
+ */
 struct btr_pool *btr_pool_new(const char *name, size_t area_size)
 {
        struct btr_pool *btrp;
@@ -70,8 +82,11 @@ struct btr_pool *btr_pool_new(const char *name, size_t area_size)
        return btrp;
 }
 
-/* whead = NULL means area full */
-
+/**
+ * Dellocate resources used by a buffer pool.
+ *
+ * \param btrp A pointer obtained via btr_pool_new().
+ */
 void btr_pool_free(struct btr_pool *btrp)
 {
        if (!btrp)
@@ -81,6 +96,14 @@ void btr_pool_free(struct btr_pool *btrp)
        free(btrp);
 }
 
+/**
+ * Return the size of the buffer pool area.
+ *
+ * \param btrp The buffer pool.
+ *
+ * \return The same value which was passed during creation time to
+ * btr_pool_new().
+ */
 size_t btr_pool_size(struct btr_pool *btrp)
 {
        return btrp->area_end - btrp->area_start;
@@ -113,6 +136,15 @@ size_t btr_pool_available(struct btr_pool *btrp)
        return btrp->rhead - btrp->whead;
 }
 
+/**
+ * Obtain the current write head.
+ *
+ * \param btrp The buffer pool.
+ * \param result The write head is returned here.
+ *
+ * \return The maximal amount of bytes that may be written to the returned
+ * buffer.
+ */
 size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result)
 {
        if (result)
@@ -120,7 +152,16 @@ size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result)
        return btr_pool_available(btrp);
 }
 
-void btr_pool_allocate(struct btr_pool *btrp, size_t size)
+/**
+ * Mark a part of the buffer pool area as allocated.
+ *
+ * \param btrp The buffer pool.
+ * \param size The amount of bytes to be allocated.
+ *
+ * This is usually called after the caller wrote to the buffer obtained by
+ * btr_pool_get_buffer().
+ */
+static void btr_pool_allocate(struct btr_pool *btrp, size_t size)
 {
        char *end;
 
@@ -168,14 +209,6 @@ 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)
 
-/*
-       (parent, child):
-       (NULL, NULL): new, isolated node.
-       (p, NULL): new leaf node
-       (NULL, c): new node becomes root, c must be old root
-       (p, c): new internal node, ch must be child of p, not yet implemented
-
-*/
 struct btr_node *btr_new_node(struct btr_node_description *bnd)
 {
        struct btr_node *btrn = para_malloc(sizeof(*btrn));
@@ -292,6 +325,12 @@ void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
        add_btrb_to_children(btrb, btrn, 0);
 }
 
+/**
+ * Feed data to child nodes of the buffer tree.
+ *
+ * \param btrp The buffer pool.
+ * 
+ */
 void btr_add_output_pool(struct btr_pool *btrp, size_t size,
                struct btr_node *btrn)
 {
@@ -310,6 +349,17 @@ void btr_add_output_pool(struct btr_pool *btrp, size_t size,
        add_btrb_to_children(btrb, btrn, 0);
 }
 
+/**
+ * Copy data to write head of a buffer pool and feed it to all children nodes.
+ *
+ * \param src The source buffer.
+ * \param n The size of the source buffer in bytes.
+ * \param btrp The destination buffer pool.
+ * \param btrn Add the data as output of this node.
+ *
+ * This is expensive. The caller must make sure the data fits into the buffer
+ * pool area.
+ */
 void btr_copy(const void *src, size_t n, struct btr_pool *btrp,
        struct btr_node *btrn)
 {