X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=buffer_tree.h;h=3ee469c91b3fe56583b305fbb5dcb92d6ac9a4aa;hp=0634e63c595ac8adf74dfc235e1e8dd9c9ccd59f;hb=6ba4caacaeb4ac2d8e5fc15699bf89f496d59901;hpb=6793399f34237840fbf48220971966bc9a3d5a18 diff --git a/buffer_tree.h b/buffer_tree.h index 0634e63c..3ee469c9 100644 --- a/buffer_tree.h +++ b/buffer_tree.h @@ -1,18 +1,25 @@ +/* + * Copyright (C) 2009 Andre Noll + * + * 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 linked via certain parent/child * relationships. * + * 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 * that buffer are created for all children of the node. The buffer tree code @@ -23,10 +30,7 @@ * 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 @@ -37,21 +41,21 @@ struct btr_node; * 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 @@ -70,7 +74,7 @@ struct btr_node; * 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. * @@ -81,6 +85,8 @@ struct btr_node; * remaining part of the area only. This only happens when the end of the area * is reached. */ + +struct btr_node; struct btr_pool; /** @@ -168,7 +174,7 @@ 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); +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); @@ -176,26 +182,26 @@ void btr_copy(const void *src, size_t n, 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);