From 7faa0f554231900fea2eb1dfc45fac3a18f94ea2 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Tue, 19 Jan 2010 02:44:40 +0100 Subject: [PATCH] [btr] Add more documentation. --- buffer_tree.c | 82 ++++++++++++++++++++++++++++++++++++++++++++++----- buffer_tree.h | 1 - 2 files changed, 75 insertions(+), 8 deletions(-) diff --git a/buffer_tree.c b/buffer_tree.c index aff03444..201fb0b0 100644 --- a/buffer_tree.c +++ b/buffer_tree.c @@ -57,8 +57,7 @@ struct btr_node { * Create a new buffer pool. * * \param name The name of the new buffer pool. - * - * \param area The size in bytes of the pool area. + * \param area_size 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 @@ -79,7 +78,7 @@ struct btr_pool *btr_pool_new(const char *name, size_t area_size) } /** - * Dellocate resources used by a buffer pool. + * Deallocate resources used by a buffer pool. * * \param btrp A pointer obtained via btr_pool_new(). */ @@ -222,9 +221,9 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size) * * \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(). + * 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(). */ struct btr_node *btr_new_node(struct btr_node_description *bnd) { @@ -424,6 +423,15 @@ static void btr_pushdown_br(struct btr_buffer_reference *br, struct btr_node *bt btr_drop_buffer_reference(br); } +/** + * Feed all buffer references of the input queue through the output channel. + * + * \param btrn The node whose buffer references should be pushed down. + * + * This function is useful for filters that do not change the contents of the + * buffers at all, like the wav filter or the amp filter if no amplification + * was specified. This function is rather cheap. + */ void btr_pushdown(struct btr_node *btrn) { struct btr_buffer_reference *br, *tmp; @@ -596,6 +604,11 @@ static void flush_input_queue(struct btr_node *btrn) btr_drop_buffer_reference(br); } +/** + * Free all resources allocated by 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) { if (!btrn) @@ -604,6 +617,17 @@ void btr_free_node(struct btr_node *btrn) free(btrn); } +/** + * Remove a node from a buffer tree. + * + * \param btrn The node to remove. + * + * This makes all child nodes of \a btrn orphans and removes \a btrn from the + * list of children of its parent. Moreover, the input queue of \a btrn is + * flushed if it is not empty. + * + * \sa \ref btr_splice_out_node. + */ void btr_remove_node(struct btr_node *btrn) { struct btr_node *ch; @@ -646,6 +670,17 @@ size_t btr_get_input_queue_size(struct btr_node *btrn) return size; } +/** + * Remove a node from the buffer tree, reconnecting parent and children. + * + * \param btrn The node to splice out. + * + * This function is used by buffer tree nodes that do not exist during the + * whole lifetime of the buffer tree. Unlike btr_remove_node(), calling + * btr_splice_out_node() does not split the tree into disconnected components + * but reconnects the buffer tree by making all child nodes of \a btrn children + * of the parent of \a btrn. + */ void btr_splice_out_node(struct btr_node *btrn) { struct btr_node *ch, *tmp; @@ -692,7 +727,18 @@ int btr_exec(struct btr_node *btrn, const char *command, char **value_result) } /** - * Execute a inter-node command. + * Execute a inter-node command on a parent node. + * + * \param btrn The node to start looking. + * \param command The command to execute. + * \param value_result Additional arguments and result value. + * + * This function traverses the buffer tree upwards and looks for parent nodes + * of \a btrn that understands \a command. On the first such node the command + * is executed, and the result is stored in \a value_result. + * + * \return \p -ENOTSUP if no parent node of \a btrn understands \a command. + * Otherwise the return value of the command handler is returned. */ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result) { @@ -718,6 +764,14 @@ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result) return -ERRNO_TO_PARA_ERROR(ENOTSUP); } +/** + * Obtain the context of a buffer node tree. + * + * The returned pointer equals the context pointer used at creation time of the + * node. + * + * \sa btr_new_node(), struct \ref btr_node_description. + */ void *btr_context(struct btr_node *btrn) { return btrn->context; @@ -869,6 +923,20 @@ static int merge_input(struct btr_node *btrn) return 2; } +/** + * Combine input queue buffers. + * + * \param btrn The buffer tree node whose input should be merged. + * \param dest_size Stop merging if a buffer of at least this size exists. + * + * Used to combine as many buffers as needed into a single buffer whose size is + * at least \a dest_size. This function is rather cheap in case the parent node + * uses buffer pools and rather expensive otherwise. + * + * Note that if less than \a dest_size bytes are available in total, this + * function does nothing and subsequent calls to btr_next_buffer() will still + * return a buffer size less than \a dest_size. + */ void btr_merge(struct btr_node *btrn, size_t dest_size) { if (need_buffer_pool_merge(btrn)) diff --git a/buffer_tree.h b/buffer_tree.h index 157c17c2..305fb7d1 100644 --- a/buffer_tree.h +++ b/buffer_tree.h @@ -187,7 +187,6 @@ void btr_splice_out_node(struct btr_node *btrn); void btr_pushdown(struct btr_node *btrn); void *btr_context(struct btr_node *btrn); void btr_merge(struct btr_node *btrn, size_t dest_size); -bool btr_eof(struct btr_node *btrn); void btr_log_tree(struct btr_node *btrn, int loglevel); int btr_pushdown_one(struct btr_node *btrn); bool btr_inplace_ok(struct btr_node *btrn); -- 2.39.2