1.. _Using_Circular_Buffers:
2
3Using Circular Buffers
4======================
5
6
7Circular buffers can sometimes be used to minimize the overhead of
8allocating and freeing the items passed between pipeline filters. If the
9first filter to create an item and last filter to consume an item are
10both ``serial_in_order``, the items can be allocated and freed via a
11circular buffer of size at least ``ntoken``, where ``ntoken`` is the
12first parameter to ``parallel_pipeline``. Under these conditions, no
13checking of whether an item is still in use is necessary.
14
15
16The reason this works is that at most ``ntoken`` items can be in flight,
17and items will be freed in the order that they were allocated. Hence by
18the time the circular buffer wraps around to reallocate an item, the
19item must have been freed from its previous use in the pipeline. If the
20first and last filter are *not* ``serial_in_order``, then you have to
21keep track of which buffers are currently in use, because buffers might
22not be retired in the same order they were allocated.
23
24