server: Include git version in output of com_si().

[paraslash.git] / buffer_tree.h

diff --git a/buffer_tree.h b/buffer_tree.h
index 0bb31b188a952cdcf08075af1d4374dc896d1533..fcf9df62570a6a2bab3acc1fc1a54831b541ccc4 100644 (file)
--- a/buffer_tree.h
+++ b/buffer_tree.h
@@ -1,18 +1,25 @@
+/*
+ * Copyright (C) 2009-2011 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).
  *
  * 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.
  *
  * 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
  * 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.
  * 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
  * 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.
  *
  * 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
  *
  * 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
  *
  * 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
  * 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
  * 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.
  *
  * 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.
  */
  * remaining part of the area only. This only happens when the end of the area
  * is reached.
  */

+
+struct btr_node;

 struct btr_pool;
 
 /**
 struct btr_pool;
 
 /**


@@ -168,6 +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);
 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);

+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);
 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);


@@ -178,23 +185,21 @@ 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_add_output(char *buf, size_t size, struct btr_node *btrn);
 void btr_remove_node(struct btr_node *btrn);
 void btr_free_node(struct btr_node *btrn);
 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);

 size_t btr_get_input_queue_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);
 void btr_consume(struct btr_node *btrn, size_t numbytes);
 bool btr_no_parent(struct btr_node *btrn);
 size_t btr_next_buffer(struct btr_node *btrn, 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_pushdown(struct btr_node *btrn);
 void *btr_context(struct btr_node *btrn);
 void btr_merge(struct btr_node *btrn, size_t dest_size);
 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_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);
 void btr_log_tree(struct btr_node *btrn, int loglevel);

-int btr_pushdown_one(struct btr_node *btrn);
+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);
 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);