1 //*****************************************************************
2 /*
3   JackTrip: A System for High-Quality Audio Network Performance
4   over the Internet
5 
6   Copyright (c) 2008 Juan-Pablo Caceres, Chris Chafe.
7   SoundWIRE group at CCRMA, Stanford University.
8 
9   Permission is hereby granted, free of charge, to any person
10   obtaining a copy of this software and associated documentation
11   files (the "Software"), to deal in the Software without
12   restriction, including without limitation the rights to use,
13   copy, modify, merge, publish, distribute, sublicense, and/or sell
14   copies of the Software, and to permit persons to whom the
15   Software is furnished to do so, subject to the following
16   conditions:
17 
18   The above copyright notice and this permission notice shall be
19   included in all copies or substantial portions of the Software.
20 
21   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
23   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
25   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
26   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
28   OTHER DEALINGS IN THE SOFTWARE.
29 */
30 //*****************************************************************
31 
32 /**
33  * \file RingBuffer.h
34  * \author Juan-Pablo Caceres
35  * \date July 2008
36  */
37 
38 #ifndef __RINGBUFFER_H__
39 #define __RINGBUFFER_H__
40 
41 #include <QWaitCondition>
42 #include <QMutex>
43 #include <QMutexLocker>
44 
45 #include "jacktrip_types.h"
46 
47 #include <atomic>
48 
49 //using namespace JackTripNamespace;
50 
51 
52 /** \brief Provides a ring-buffer (or circular-buffer) that can be written to and read from
53  * asynchronously (blocking) or synchronously (non-blocking).
54  *
55  * The RingBuffer is an array of \b NumSlots slots of memory
56  * each of which is of size \b SlotSize bytes (8-bits). Slots can be read and
57  * written asynchronously/synchronously by multiple threads.
58  */
59 class RingBuffer
60 {
61 public:
62 
63     /** \brief The class constructor
64    * \param SlotSize Size of one slot in bytes
65    * \param NumSlots Number of slots
66    */
67     RingBuffer(int SlotSize, int NumSlots);
68 
69     /** \brief The class destructor
70    */
71     virtual ~RingBuffer();
72 
73     /** \brief Insert a slot into the RingBuffer from ptrToSlot. This method will block until
74    * there's space in the buffer.
75    *
76    * The caller is responsible to make sure sizeof(WriteSlot) = SlotSize. This
77    * method should be use when the caller can block against its output, like
78    * sending/receiving UDP packets. It shouldn't be used by audio. For that, use the
79    * insertSlotNonBlocking.
80    * \param ptrToSlot Pointer to slot to insert into the RingBuffer
81    */
82     void insertSlotBlocking(const int8_t* ptrToSlot);
83 
84     /** \brief Read a slot from the RingBuffer into ptrToReadSlot. This method will block until
85    * there's space in the buffer.
86    *
87    * The caller is responsible to make sure sizeof(ptrToReadSlot) = SlotSize. This
88    * method should be use when the caller can block against its input, like
89    * sending/receiving UDP packets. It shouldn't be used by audio. For that, use the
90    * readSlotNonBlocking.
91    * \param ptrToReadSlot Pointer to read slot from the RingBuffer
92    */
93     void readSlotBlocking(int8_t* ptrToReadSlot);
94 
95     /** \brief Same as insertSlotBlocking but non-blocking (asynchronous)
96    * \param ptrToSlot Pointer to slot to insert into the RingBuffer
97    */
98     virtual bool insertSlotNonBlocking(const int8_t* ptrToSlot, int len, int lostLen);
99 
100     /** \brief Same as readSlotBlocking but non-blocking (asynchronous)
101    * \param ptrToReadSlot Pointer to read slot from the RingBuffer
102    */
103     virtual void readSlotNonBlocking(int8_t* ptrToReadSlot);
104     virtual void readBroadcastSlot(int8_t* ptrToReadSlot);
105 
106     struct IOStat {
107         uint32_t underruns;
108         uint32_t overflows;
109         int32_t skew;
110         int32_t skew_raw;
111         int32_t level;
112         uint32_t buf_dec_overflows;
113         uint32_t buf_dec_pktloss;
114         uint32_t buf_inc_underrun;
115         uint32_t buf_inc_compensate;
116         int32_t broadcast_skew;
117         int32_t broadcast_delta;
118 
119         int32_t autoq_corr;
120         int32_t autoq_rate;
121     };
122     virtual bool getStats(IOStat* stat, bool reset);
123 
124 protected:
125 
126     /** \brief Sets the memory in the Read Slot when uderrun occurs. By default,
127    * this sets it to 0. Override this method in a subclass for a different behavior.
128    * \param ptrToReadSlot Pointer to read slot from the RingBuffer
129    */
130     virtual void setUnderrunReadSlot(int8_t* ptrToReadSlot);
131 
132     /** \brief Uses the last read slot to set the memory in the Read Slot.
133    *
134    * The last read slot is the last packet that arrived, so if no new packets are received,
135    * it keeps looping the same packet.
136    * \param ptrToReadSlot Pointer to read slot from the RingBuffer
137    */
138     virtual void setMemoryInReadSlotWithLastReadSlot(int8_t* ptrToReadSlot);
139 
140     /// \brief Resets the ring buffer for reads under-runs non-blocking
141     void underrunReset();
142     /// \brief Resets the ring buffer for writes over-flows non-blocking
143     void overflowReset();
144     /// \brief Helper method to debug, prints member variables to terminal
145     void debugDump() const;
146     void updateReadStats();
147 
148     /*const*/ int mSlotSize; ///< The size of one slot in byes
149     /*const*/ int mNumSlots; ///< Number of Slots
150     /*const*/ int mTotalSize; ///< Total size of the mRingBuffer = mSlotSize*mNumSlotss
151     uint32_t mReadPosition; ///< Read Positions in the RingBuffer (Tail)
152     uint32_t mWritePosition; ///< Write Position in the RingBuffer (Head)
153     int mFullSlots; ///< Number of used (full) slots, in slot-size
154     int8_t* mRingBuffer; ///< 8-bit array of data (1-byte)
155     int8_t* mLastReadSlot; ///< Last slot read
156 
157     // Thread Synchronization Private Members
158     QMutex mMutex; ///< Mutex to protect read and write operations
159     QWaitCondition mBufferIsNotFull; ///< Buffer not full condition to monitor threads
160     QWaitCondition mBufferIsNotEmpty; ///< Buffer not empty condition to monitor threads
161 
162     // IO stat
163     int mStatUnit;
164     uint32_t mUnderruns;
165     uint32_t mOverflows;
166     int32_t  mSkewRaw;
167     double   mLevelCur;
168     double   mLevelDownRate;
169     int32_t  mLevel;
170 
171     uint32_t mBufDecOverflow;
172     uint32_t mBufDecPktLoss;
173     uint32_t mBufIncUnderrun;
174     uint32_t mBufIncCompensate;
175 
176     // temp counters for reads
177     uint32_t mReadsNew;
178     uint32_t mUnderrunsNew;
179     int32_t  mSkew0;
180 
181     // broadcast counters
182     int32_t mBroadcastSkew;
183     int32_t mBroadcastDelta;
184 };
185 
186 #endif
187