X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=buffer_tree.h;h=0bb31b188a952cdcf08075af1d4374dc896d1533;hp=d91d43648e6e69ad6e4d54f98c6d68eecbc68ec2;hb=d9676861067ac426429a3b76fb5cb237a706d5b3;hpb=fcd1513e07cbb51179ad6da17a0d983d44dd36dd

diff --git a/buffer_tree.h b/buffer_tree.h
index d91d4364..0bb31b18 100644
--- a/buffer_tree.h
+++ b/buffer_tree.h
@@ -10,26 +10,8 @@
  * 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.
- *
- * 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.
+ * A buffer tree consists of buffer tree nodes linked via certain parent/child
+ * relationships.
  *
  * 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
@@ -99,21 +81,86 @@ struct btr_node;
  * remaining part of the area only. This only happens when the end of the area
  * is reached.
  */
-
 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;
 };
 
@@ -121,7 +168,6 @@ size_t btr_pool_size(struct btr_pool *btrp);
 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);
 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);