github.com/jwowillo/pipe@v1.2.0/doc/design.md (about)

     1  # Design
     2  
     3  ## v1.0.0
     4  
     5  ```
     6  interface Stage:
     7  * Handle(Item) Item: Handles the Item to be moved through the Pipe.
     8  ```
     9  
    10  `Stage` corresponds to stages of computations in 1. `Item` refers to any type
    11  satsfying 6.
    12  
    13  ```
    14  StageFunc func(Item) Item
    15  ```
    16  
    17  `StageFunc` is a wrapper that converts functions which would satisfy `Stage`
    18  into `Stage`s.
    19  
    20  ```
    21  class Pipe(...Stage):
    22  * Receive(Item): Receive puts the Item in the Pipe to be processes.
    23  * Deliver() Item: Deliver blocks until an Item is done being processed and
    24    returns it.
    25  ```
    26  
    27  `Pipe` connects Stages in the given order satisfying 4 and the rest of 1.
    28  `Receive` and `Deliver` hide concurrency by immediately returning after putting
    29  an `Item` in the `Pipe` and blocking until an `Item` is done satisfying 5.
    30  Concurrent functions are started for every `Stage` whenever the `Pipe` has an
    31  `Item` that handles `Item`s concurrently when available then places them in the
    32  next `Stage` satisfying 2 and 3. These functions exit when the `Pipe` is empty.
    33  `Pipe` accepts varargs since the more common use-case involves a hard-coded list
    34  of `Stage`s.
    35  
    36  ```
    37  func Process(Pipe, ...Item) []Item
    38  ```
    39  
    40  `Process` is a utility to run many `Item`s through a `Pipe`. It accepts varargs
    41  so that arguments don't need to be put in a `[]Item` from their original type.
    42  
    43  ## v1.1.0
    44  
    45  ```
    46  interface Consumer:
    47  * Consume(Item): Consumes the Item.
    48  ```
    49  
    50  `Consumer` corresponds to the consumer of `Item`s in 1 and receives `Item`s as
    51  they come out of the `Pipe`.
    52  
    53  ```
    54  ConsumerFunc func(Item)
    55  ```
    56  
    57  `ConsumerFunc` is a wrapper that converts functions which would satisfy
    58  `Consumer` into `Consumer`s.
    59  
    60  ```
    61  ProcessAndConsume(Pipe, Consumer, ...Item)
    62  ```
    63  
    64  `ProcessAndConsume` is a utility that works like `Process` except it passes the
    65  `Item`s to the `Consumer` as they come out of the `Pipe` as in 1.
    66  
    67  ## v1.2.0
    68  
    69  ```
    70  interface Producer:
    71  * Produce() (Item, bool)
    72  ```
    73  
    74  `Producer` corresponds to the producer of `Item`s in 1 and gives `Item`s to the
    75  `Pipe` until the `Producer` returns false. The `Item` returned with the false
    76  value is ignored.
    77  
    78  ```
    79  ProducerFunc func() (Item, bool)
    80  ```
    81  
    82  `ProducerFunc` is a wrapper that converts functions which would satisfy
    83  `Producer` into `Producer`s.
    84  
    85  ```
    86  func ProduceAndProcess(Pipe, Producer) []Item
    87  ```
    88  
    89  `ProduceAndProcess` is a utility that works like `Process` except it produces
    90  `Item`s from the `Producer` to pass into the `Pipe` as in 1.
    91  
    92  ```
    93  func ProduceProcessAndConsume(Pipe, Producer, Consumer)
    94  ```
    95  
    96  `ProduceProcessAndConsume` is a utility that works like `Process` except it
    97  produces `Item`s from the `Producer` to pass into the `Pipe` and it passes the
    98  `Item`s to the `Consumer` as they come out of the `Pipe` as in 1.
    99