From d63f84b1a243ce5d0a7d13928d9f522d7f5b476b Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Mon, 2 Jan 2023 15:07:31 +0100 Subject: [PATCH] btr: Streamline the documentation of buffer_tree.h. Nothing major, just a few minor English issues. --- buffer_tree.h | 44 +++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/buffer_tree.h b/buffer_tree.h index 5eb3d6e5..70fb3055 100644 --- a/buffer_tree.h +++ b/buffer_tree.h @@ -3,45 +3,43 @@ /** * \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). + * Buffer trees and buffer tree nodes. * - * A buffer tree consists of buffer tree nodes linked via certain parent/child - * relationships. + * The buffer tree API offers an efficient method for managing the data flow + * from a producer (e.g. the network receiver) to the consumer(s) (e.g. a sound + * card). + * + * A buffer tree consists of buffer tree nodes which are linked together via + * parent/child relationships. Data buffers are propagated down without copying. * * 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(). + * each child. There are no file descriptors, no processes/threads 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 - * tries hard to avoid to copy buffer contents, but is forced to do so in case - * there are alignment constraints. + * that buffer are created for all children of the node. The code avoids to + * copy buffer contents when possible. * - * Communication between nodes is possible via the btr_exec_up() function. - * 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. + * Communication between nodes is possible via the btr_exec_up() function. For + * example, in para_audiod the alsa writer asks all parent nodes for the number + * of channels and the sample rate of the current audio file. * * Buffer pools - An alternative to malloc/free buffer management. * - * Non-leaf nodes usually create output to be processed by their children. The - * data must be fed through the output channel(s) of the node in order to make - * that data available to each child. + * Non-leaf nodes usually create output to be processed by their child nodes. + * The data must be fed through the output channel(s) of the node in order to + * make that data available to each child. * * The easiest way to do so is to malloc() a buffer, fill it, and then call * 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 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. + * This approach is simple but has some drawbacks. For example the data source + * represented by the root node does not know in advance how much data will be + * available. Therefore the allocated buffer will either be larger than + * necessary or 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 -- 2.39.5