+/**
+ * Buffer pools - An alternative to malloc/free buffer management.
+ *
+ * Non-leaf nodes usually create output to be processed by their children. The
+ * data must be fed through the output channel(s) of the node in order to make
+ * that data available to each child.
+ *
+ * The easiest way to do so is to malloc() a buffer, fill it, and then call
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * contents around in order to satisfy the constraint.
+ *
+ * This is where buffer pools come into play. Buffer pools try to satisfy
+ * alignment constraints without copying buffer content whenever possible. To
+ * avoid spreading out the input data over the address space like in the
+ * malloc/free approach, a fixed large contiguous buffer (the area) is used
+ * instead. A buffer pool consists basically of an area and two pointers, the
+ * read head and the write head.
+ *
+ * Once a buffer pool has been created, its node, e.g. a receiver, obtains the
+ * current value of the write head and writes new data to this location. Then
+ * it calls btr_add_output_pool() to tell much data it has written. This
+ * advances the write head accordingly, and it also creates references to the
+ * newly written part of the area for the children of the node to consume.
+ *
+ * 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
+ * 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.
+ *
+ * No matter if malloc() or a buffer pool is used, the buffer tree code takes
+ * care of alignment constraints imposed by the consumers. In the buffer pool
+ * case, automatic merging of references to contiguous buffers is performed.
+ * memcpy is only used if a constraint can not be satisfied by using the
+ * remaining part of the area only. This only happens when the end of the area
+ * is reached.
+ */
+struct btr_pool;
+
+/**
+ * The three different types of buffer tree nodes.
+ *
+ * Usually, there is exactly one node in the buffer tree, the root node, which
+ * has no parent. Every node different from the root node has exactly one
+ * parent. The root node represents a data source. Root nodes are thus used by
+ * the receivers of paraslash. Also, reading from stdin is realized as the root
+ * node of a buffer tree.
+ *
+ * Each node may have arbitrary many children, including none. Nodes with no
+ * children are called leaf nodes. They represent a data sink, like the alsa or
+ * the file writer.
+ *
+ * Hence there are three different types of buffer tree nodes: The root node
+ * and the leaf nodes and nodes which have both a parent and at least one
+ * child. Such a node is called an internal node.
+ *
+ * Internal nodes represent filters through which data buffers flow, possibly
+ * while being altered on their way to the children of the node. Examples of
+ * internal nodes are audio file decoders (mp3dec, oggdec, ...), but also the
+ * check for a wav header is implemented as an internal buffer tree node.
+ */
+enum btr_node_type {
+ /* This node has no parent. */
+ BTR_NT_ROOT,
+ /* Node has parent and at least one child. */
+ BTR_NT_INTERNAL,
+ /* Node has no children. */
+ BTR_NT_LEAF,
+};
+
+/**
+ * Per node handler used for inter node communication.
+ *
+ * Each node in the buffer tree may optionally provide a command handler for
+ * execution of commands by other nodes of the tree.
+ *
+ * It is dependent on the node in question which commands are supported and how
+ * they work. In any case, the input for the command handler is some string and
+ * its output is also a string which is returned via the \a result pointer of
+ * the handler.
+ *
+ * This mechanism is used in para_audiod e.g. by the alsa writer which needs to
+ * know the sample rate of its input known to e.g. the mp3dec node further up
+ * in the buffer tree.
+ */