/*
- * 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.
*/
*
* \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().
*
* 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
numbytes -= br->btrb->size - br->consumed;
btr_drop_buffer_reference(br);
}
- assert(true);
+ assert(false);
}
/*
* We have a wrap buffer, consume from it. If in total, i.e. including
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);
}
/**
* 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)
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);
}
*
* \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)
{
/**
* 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.
*/