juce/source/src/containers/juce_AbstractFifo.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_ABSTRACTFIFO_JUCEHEADER__
  27 #define __JUCE_ABSTRACTFIFO_JUCEHEADER__
  28
  29 #include "../memory/juce_Atomic.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     Encapsulates the logic required to implement a lock-free FIFO.
  35
  36     This class handles the logic needed when building a single-reader, single-writer FIFO.
  37
  38     It doesn't actually hold any data itself, but your FIFO class can use one of these to manage
  39     its position and status when reading or writing to it.
  40
  41     To use it, you can call prepareToWrite() to determine the position within your own buffer that
  42     an incoming block of data should be stored, and prepareToRead() to find out when the next
  43     outgoing block should be read from.
  44
  45     e.g.
  46     @code
  47     class MyFifo
  48     {
  49     public:
  50         MyFifo()  : abstractFifo (1024)
  51         {
  52         }
  53
  54         void addToFifo (const int* someData, int numItems)
  55         {
  56             int start1, size1, start2, size2;
  57             prepareToWrite (numItems, start1, size1, start2, size2);
  58
  59             if (size1 > 0)
  60                 copySomeData (myBuffer + start1, someData, size1);
  61
  62             if (size2 > 0)
  63                 copySomeData (myBuffer + start2, someData + size1, size2);
  64
  65             finishedWrite (size1 + size2);
  66         }
  67
  68         void readFromFifo (int* someData, int numItems)
  69         {
  70             int start1, size1, start2, size2;
  71             prepareToRead (numSamples, start1, size1, start2, size2);
  72
  73             if (size1 > 0)
  74                 copySomeData (someData, myBuffer + start1, size1);
  75
  76             if (size2 > 0)
  77                 copySomeData (someData + size1, myBuffer + start2, size2);
  78
  79             finishedRead (size1 + size2);
  80         }
  81
  82     private:
  83         AbstractFifo abstractFifo;
  84         int myBuffer [1024];
  85     };
  86     @endcode
  87 */
  88 class JUCE_API  AbstractFifo
  89 {
  90 public:
  91     //==============================================================================
  92     /** Creates a FIFO to manage a buffer with the specified capacity. */
  93     AbstractFifo (int capacity) noexcept;
  94
  95     /** Destructor */
  96     ~AbstractFifo();
  97
  98     //==============================================================================
  99     /** Returns the total size of the buffer being managed. */
 100     int getTotalSize() const noexcept;
 101
 102     /** Returns the number of items that can currently be added to the buffer without it overflowing. */
 103     int getFreeSpace() const noexcept;
 104
 105     /** Returns the number of items that can currently be read from the buffer. */
 106     int getNumReady() const noexcept;
 107
 108     /** Clears the buffer positions, so that it appears empty. */
 109     void reset() noexcept;
 110
 111     /** Changes the buffer's total size.
 112         Note that this isn't thread-safe, so don't call it if there's any danger that it
 113         might overlap with a call to any other method in this class!
 114     */
 115     void setTotalSize (int newSize) noexcept;
 116
 117     //==============================================================================
 118     /** Returns the location within the buffer at which an incoming block of data should be written.
 119
 120         Because the section of data that you want to add to the buffer may overlap the end
 121         and wrap around to the start, two blocks within your buffer are returned, and you
 122         should copy your data into the first one, with any remaining data spilling over into
 123         the second.
 124
 125         If the number of items you ask for is too large to fit within the buffer's free space, then
 126         blockSize1 + blockSize2 may add up to a lower value than numToWrite. If this happens, you
 127         may decide to keep waiting and re-trying the method until there's enough space available.
 128
 129         After calling this method, if you choose to write your data into the blocks returned, you
 130         must call finishedWrite() to tell the FIFO how much data you actually added.
 131
 132         e.g.
 133         @code
 134         void addToFifo (const int* someData, int numItems)
 135         {
 136             int start1, size1, start2, size2;
 137             prepareToWrite (numItems, start1, size1, start2, size2);
 138
 139             if (size1 > 0)
 140                 copySomeData (myBuffer + start1, someData, size1);
 141
 142             if (size2 > 0)
 143                 copySomeData (myBuffer + start2, someData + size1, size2);
 144
 145             finishedWrite (size1 + size2);
 146         }
 147         @endcode
 148
 149         @param numToWrite       indicates how many items you'd like to add to the buffer
 150         @param startIndex1      on exit, this will contain the start index in your buffer at which your data should be written
 151         @param blockSize1       on exit, this indicates how many items can be written to the block starting at startIndex1
 152         @param startIndex2      on exit, this will contain the start index in your buffer at which any data that didn't fit into
 153                                 the first block should be written
 154         @param blockSize2       on exit, this indicates how many items can be written to the block starting at startIndex2
 155         @see finishedWrite
 156     */
 157     void prepareToWrite (int numToWrite, int& startIndex1, int& blockSize1, int& startIndex2, int& blockSize2) const noexcept;
 158
 159     /** Called after reading from the FIFO, to indicate that this many items have been added.
 160         @see prepareToWrite
 161     */
 162     void finishedWrite (int numWritten) noexcept;
 163
 164     /** Returns the location within the buffer from which the next block of data should be read.
 165
 166         Because the section of data that you want to read from the buffer may overlap the end
 167         and wrap around to the start, two blocks within your buffer are returned, and you
 168         should read from both of them.
 169
 170         If the number of items you ask for is greater than the amount of data available, then
 171         blockSize1 + blockSize2 may add up to a lower value than numWanted. If this happens, you
 172         may decide to keep waiting and re-trying the method until there's enough data available.
 173
 174         After calling this method, if you choose to read the data, you must call finishedRead() to
 175         tell the FIFO how much data you have consumed.
 176
 177         e.g.
 178         @code
 179         void readFromFifo (int* someData, int numItems)
 180         {
 181             int start1, size1, start2, size2;
 182             prepareToRead (numSamples, start1, size1, start2, size2);
 183
 184             if (size1 > 0)
 185                 copySomeData (someData, myBuffer + start1, size1);
 186
 187             if (size2 > 0)
 188                 copySomeData (someData + size1, myBuffer + start2, size2);
 189
 190             finishedRead (size1 + size2);
 191         }
 192         @endcode
 193
 194         @param numWanted        indicates how many items you'd like to add to the buffer
 195         @param startIndex1      on exit, this will contain the start index in your buffer at which your data should be written
 196         @param blockSize1       on exit, this indicates how many items can be written to the block starting at startIndex1
 197         @param startIndex2      on exit, this will contain the start index in your buffer at which any data that didn't fit into
 198                                 the first block should be written
 199         @param blockSize2       on exit, this indicates how many items can be written to the block starting at startIndex2
 200         @see finishedRead
 201     */
 202     void prepareToRead (int numWanted, int& startIndex1, int& blockSize1, int& startIndex2, int& blockSize2) const noexcept;
 203
 204     /** Called after reading from the FIFO, to indicate that this many items have now been consumed.
 205         @see prepareToRead
 206     */
 207     void finishedRead (int numRead) noexcept;
 208
 209
 210 private:
 211     //==============================================================================
 212     int bufferSize;
 213     Atomic <int> validStart, validEnd;
 214
 215     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AbstractFifo);
 216 };
 217
 218
 219 #endif   // __JUCE_ABSTRACTFIFO_JUCEHEADER__