1 /**
2 High-level interface for $(B flod). Provides the most commonly used functions of the package.
4 Package_description:
6 $(B flod) is a library for processing streams of data using composable building blocks.
8 In $(B flod), a $(I pipeline) is a chain of one or more $(I stages), which communicate with
9 each other using the specified interfaces.
11 A stage can be either a $(I source), a $(I sink), or a $(I filter), which is
12 both a sink and a source. A source-only stage is one that only produces data, e.g.
13 reads a file or generates random bytes. A sink-only stage is one that only consumes
14 data from previous stages. For example, a sink may use the data to build an array or replay
15 audio samples. A filter stage receives data on its sink end,
16 and produces transformed data on its source end. Examples of such stages are media decoders
17 or cipher implementations.
19 There are four methods of passing data from a source to a sink:
20 $(TABLE
21  $(TR $(TH method)     $(TH description)                                         $(TH buffer is owned by))
22  $(TR $(TD $(I pull))  $(TD `sink` calls `source.pull()`)                        $(TD sink))
23  $(TR $(TD $(I push))  $(TD `source` calls `sink.push()`)                        $(TD source))
24  $(TR $(TD $(I peek))  $(TD `sink` calls `source.peek()` and `source.consume()`) $(TD source))
25  $(TR $(TD $(I alloc)) $(TD `source` calls `sink.alloc()` and `sink.commit()`)   $(TD sink))
26 )
28 Note that a filter can use different methods for its sink and source ends. For example, it may
29 call `peek` and `consume` to access the input data, and output transformed data using `push`.
31 Authors: $(LINK2 https://github.com/epi, Adrian Matoga)
32 Copyright: © 2016 Adrian Matoga
33 License: $(LINK2 http://www.boost.org/users/license.html, BSL-1.0).
34 */
35 module flod;
37 public import flod.range : copy;