+/*
+ * Copyright (C) 2009-2014 Andre Noll <maan@systemlinux.org>
+ *
+ * Licensed under the GPL v2. For licencing details see COPYING.
+ */
+
/**
- * 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. 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.
+ * A buffer tree consists of buffer tree nodes linked via certain parent/child
+ * relationships.
*
- * 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.
+ * 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
* 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
* 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
* 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.
*
* is reached.
*/
+struct btr_node;
struct btr_pool;
-typedef int (*btr_command_handler)(struct btr_node *btrn,
- const char *command, char **result);
+/**
+ * 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.
+ */
+typedef int (*btr_command_handler)(struct btr_node *btrn,
+ const char *command, char **result);
+
+/**
+ * Structure for creating new buffer tree nodes.
+ *
+ * btr_new_node() takes a pointer to such a structure.
+ *
+ * There are four different combinations of \a parent and child:
+ *
+ * 1. both \p NULL. This creates a new buffer tree with a single isolated node.
+ *
+ * 2. \a parent != \p NULL, \a child == NULL. This creates a new leaf node by
+ * adding the new node to the list of children of the given parent node.
+ *
+ * 3. \a parent == NULL, \a child != NULL. The new node becomes the new root of
+ * the buffer tree. The child must be old root.
+ *
+ * 4. both != NULL. This creates a new internal node. \a child must be child of
+ * p. This mode of operation is currently not needed and is thus not yet
+ * implemented.
+ */
struct btr_node_description {
+ /** Name of the new node. */
const char *name;
+ /** Parent of the new node. */
struct btr_node *parent;
+ /** Child of the new node. */
+ struct btr_node *child;
+ /** Used for inter node communication. Optional. */
btr_command_handler handler;
+ /** Points usually to the struct that contains the node pointer. */
void *context;
};
struct btr_pool *btr_pool_new(const char *name, size_t area_size);
void btr_pool_free(struct btr_pool *btrp);
size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result);
-void btr_pool_allocate(struct btr_pool *btrp, size_t size);
+int btr_pool_get_buffers(struct btr_pool *btrp, struct iovec iov[2]);
void btr_add_output_pool(struct btr_pool *btrp, size_t size,
struct btr_node *btrn);
size_t btr_pool_unused(struct btr_pool *btrp);
struct btr_node *btrn);
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_remove_node(struct btr_node **btrnp);
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);
+void btr_add_output_dont_free(const char *buf, size_t size, struct btr_node *btrn);
size_t btr_get_input_queue_size(struct btr_node *btrn);
+size_t btr_get_output_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);
+size_t btr_next_buffer_omit(struct btr_node *btrn, size_t omit, 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_splice_out_node(struct btr_node **btrnp);
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);
+void btr_log_tree(struct btr_node *btrn, int ll);
+void btr_pushdown_one(struct btr_node *btrn);
bool btr_inplace_ok(struct btr_node *btrn);
int btr_node_status(struct btr_node *btrn, size_t min_iqs,
enum btr_node_type type);
void btr_get_node_start(struct btr_node *btrn, struct timeval *tv);
struct btr_node *btr_search_node(const char *name, struct btr_node *root);
+void btr_drain(struct btr_node *btrn);
+struct btr_node *btr_parent(struct btr_node *btrn);
projects / paraslash.git / blobdiff