From: Andre Noll Date: Fri, 15 Jan 2010 06:41:19 +0000 (+0100) Subject: [btr] Add more documentation. X-Git-Tag: v0.4.2~91 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=6793399f34237840fbf48220971966bc9a3d5a18 [btr] Add more documentation. --- diff --git a/buffer_tree.c b/buffer_tree.c index 1ea68917..6dc3c41b 100644 --- a/buffer_tree.c +++ b/buffer_tree.c @@ -168,14 +168,6 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size) #define FOR_EACH_BUFFER_REF_SAFE(_br, _tmp, _btrn) \ list_for_each_entry_safe((_br), (_tmp), &(_btrn)->input_queue, node) -/* - (parent, child): - (NULL, NULL): new, isolated node. - (p, NULL): new leaf node - (NULL, c): new node becomes root, c must be old root - (p, c): new internal node, ch must be child of p, not yet implemented - -*/ struct btr_node *btr_new_node(struct btr_node_description *bnd) { struct btr_node *btrn = para_malloc(sizeof(*btrn)); diff --git a/buffer_tree.h b/buffer_tree.h index abba7472..0634e63c 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,22 +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; };