Debian Codegraph @

srtcore/buffer_rcv.h

raw
1 /*
2 * SRT - Secure, Reliable, Transport
3 * Copyright (c) 2020 Haivision Systems Inc.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 */
10
11 #ifndef INC_SRT_BUFFER_RCV_H
12 #define INC_SRT_BUFFER_RCV_H
13
14 #include "buffer_tools.h" // AvgBufSize
15 #include "common.h"
16 #include "queue.h"
17 #include "tsbpd_time.h"
18
19 namespace srt
20 {
21
22 /*
23 * Circular receiver buffer.
24 *
25 * |<------------------- m_szSize ---------------------------->|
26 * | |<------------ m_iMaxPosOff ----------->| |
27 * | | | |
28 * +---+---+---+---+---+---+---+---+---+---+---+---+---+ +---+
29 * | 0 | 0 | 1 | 1 | 1 | 0 | 1 | 1 | 1 | 1 | 0 | 1 | 0 |...| 0 | m_pUnit[]
30 * +---+---+---+---+---+---+---+---+---+---+---+---+---+ +---+
31 * | |
32 * | \__last pkt received
33 * |
34 * \___ m_iStartPos: first message to read
35 *
36 * m_pUnit[i]->status_: 0: free, 1: good, 2: read, 3: dropped (can be combined with read?)
37 *
38 * thread safety:
39 * start_pos_: CUDT::m_RecvLock
40 * first_unack_pos_: CUDT::m_AckLock
41 * max_pos_inc_: none? (modified on add and ack
42 * first_nonread_pos_:
43 */
44
45 class CRcvBuffer
46 {
47 typedef sync::steady_clock::time_point time_point;
48 typedef sync::steady_clock::duration duration;
49
50 public:
51 CRcvBuffer(int initSeqNo, size_t size, CUnitQueue* unitqueue, bool bMessageAPI);
52
53 ~CRcvBuffer();
54
55 public:
56 /// Insert a unit into the buffer.
57 /// Similar to CRcvBuffer::addData(CUnit* unit, int offset)
58 ///
59 /// @param [in] unit pointer to a data unit containing new packet
60 /// @param [in] offset offset from last ACK point.
61 ///
62 /// @return 0 on success, -1 if packet is already in buffer, -2 if packet is before m_iStartSeqNo.
63 /// -3 if a packet is offset is ahead the buffer capacity.
64 // TODO: Previously '-2' also meant 'already acknowledged'. Check usage of this value.
65 int insert(CUnit* unit);
66
67 /// Drop packets in the receiver buffer from the current position up to the seqno (excluding seqno).
68 /// @param [in] seqno drop units up to this sequence number
69 /// @return number of dropped (missing) and discarded (available) packets as a pair(dropped, discarded).
70 std::pair<int, int> dropUpTo(int32_t seqno);
71
72 /// @brief Drop all the packets in the receiver buffer.
73 /// The starting position and seqno are shifted right after the last packet in the buffer.
74 /// @return the number of dropped packets.
75 int dropAll();
76
77 enum DropActionIfExists {
78 DROP_EXISTING = 0,
79 KEEP_EXISTING = 1
80 };
81
82 /// @brief Drop a sequence of packets from the buffer.
83 /// If @a msgno is valid, sender has requested to drop the whole message by TTL. In this case it has to also provide a pkt seqno range.
84 /// However, if a message has been partially acknowledged and already removed from the SND buffer,
85 /// the @a seqnolo might specify some position in the middle of the message, not the very first packet.
86 /// If those packets have been acknowledged, they must exist in the receiver buffer unless already read.
87 /// In this case the @a msgno should be used to determine starting packets of the message.
88 /// Some packets of the message can be missing on the receiver, therefore the actual drop should still be performed by pkt seqno range.
89 /// If message number is 0 or SRT_MSGNO_NONE, then use sequence numbers to locate sequence range to drop [seqnolo, seqnohi].
90 /// A SOLO message packet can be kept depending on @a actionOnExisting value.
91 /// TODO: A message in general can be kept if all of its packets are in the buffer, depending on @a actionOnExisting value.
92 /// This is done to avoid dropping existing packet when the sender was asked to re-transmit a packet from an outdated loss report,
93 /// which is already not available in the SND buffer.
94 /// @param seqnolo sequence number of the first packet in the dropping range.
95 /// @param seqnohi sequence number of the last packet in the dropping range.
96 /// @param msgno message number to drop (0 if unknown)
97 /// @param actionOnExisting Should an existing SOLO packet be dropped from the buffer or preserved?
98 /// @return the number of packets actually dropped.
99 int dropMessage(int32_t seqnolo, int32_t seqnohi, int32_t msgno, DropActionIfExists actionOnExisting);
100
101 /// Read the whole message from one or several packets.
102 ///
103 /// @param [in,out] data buffer to write the message into.
104 /// @param [in] len size of the buffer.
105 /// @param [in,out] message control data
106 ///
107 /// @return actual number of bytes extracted from the buffer.
108 /// 0 if nothing to read.
109 /// -1 on failure.
110 int readMessage(char* data, size_t len, SRT_MSGCTRL* msgctrl = NULL);
111
112 /// Read acknowledged data into a user buffer.
113 /// @param [in, out] dst pointer to the target user buffer.
114 /// @param [in] len length of user buffer.
115 /// @return size of data read. -1 on error.
116 int readBuffer(char* dst, int len);
117
118 /// Read acknowledged data directly into file.
119 /// @param [in] ofs C++ file stream.
120 /// @param [in] len expected length of data to write into the file.
121 /// @return size of data read. -1 on error.
122 int readBufferToFile(std::fstream& ofs, int len);
123
124 public:
125 /// Get the starting position of the buffer as a packet sequence number.
126 int getStartSeqNo() const { return m_iStartSeqNo; }
127
128 /// Sets the start seqno of the buffer.
129 /// Must be used with caution and only when the buffer is empty.
130 void setStartSeqNo(int seqno) { m_iStartSeqNo = seqno; }
131
132 /// Given the sequence number of the first unacknowledged packet
133 /// tells the size of the buffer available for packets.
134 /// Effective returns capacity of the buffer minus acknowledged packet still kept in it.
135 // TODO: Maybe does not need to return minus one slot now to distinguish full and empty buffer.
136 size_t getAvailSize(int iFirstUnackSeqNo) const
137 {
138 // Receiver buffer allows reading unacknowledged packets.
139 // Therefore if the first packet in the buffer is ahead of the iFirstUnackSeqNo
140 // then it does not have acknowledged packets and its full capacity is available.
141 // Otherwise subtract the number of acknowledged but not yet read packets from its capacity.
142 const int iRBufSeqNo = getStartSeqNo();
143 if (CSeqNo::seqcmp(iRBufSeqNo, iFirstUnackSeqNo) >= 0) // iRBufSeqNo >= iFirstUnackSeqNo
144 {
145 // Full capacity is available.
146 return capacity();
147 }
148
149 // Note: CSeqNo::seqlen(n, n) returns 1.
150 return capacity() - CSeqNo::seqlen(iRBufSeqNo, iFirstUnackSeqNo) + 1;
151 }
152
153 /// @brief Checks if the buffer has packets available for reading regardless of the TSBPD.
154 /// A message is available for reading only if all of its packets are present in the buffer.
155 /// @return true if there are packets available for reading, false otherwise.
156 bool hasAvailablePackets() const;
157
158 /// Query how many data has been continuously received (for reading) and available for reading out
159 /// regardless of the TSBPD.
160 /// TODO: Rename to countAvailablePackets().
161 /// @return size of valid (continuous) data for reading.
162 int getRcvDataSize() const;
163
164 /// Get the number of packets, bytes and buffer timespan.
165 /// Differs from getRcvDataSize() that it counts all packets in the buffer, not only continuous.
166 int getRcvDataSize(int& bytes, int& timespan) const;
167
168 struct PacketInfo
169 {
170 int seqno;
171 bool seq_gap; //< true if there are missing packets in the buffer, preceding current packet
172 time_point tsbpd_time;
173 };
174
175 /// Get information on the 1st message in queue.
176 /// Similar to CRcvBuffer::getRcvFirstMsg
177 /// Parameters (of the 1st packet queue, ready to play or not):
178 /// @param [out] tsbpdtime localtime-based (uSec) packet time stamp including buffering delay of 1st packet or 0 if
179 /// none
180 /// @param [out] passack true if 1st ready packet is not yet acknowledged (allowed to be delivered to the app)
181 /// @param [out] skipseqno -1 or sequence number of 1st unacknowledged packet (after one or more missing packets) that is ready to play.
182 /// @retval true 1st packet ready to play (tsbpdtime <= now). Not yet acknowledged if passack == true
183 /// @retval false IF tsbpdtime = 0: rcv buffer empty; ELSE:
184 /// IF skipseqno != -1, packet ready to play preceded by missing packets.;
185 /// IF skipseqno == -1, no missing packet but 1st not ready to play.
186 PacketInfo getFirstValidPacketInfo() const;
187
188 PacketInfo getFirstReadablePacketInfo(time_point time_now) const;
189
190 /// @brief Get the sequence number of the first packet that can't be read
191 /// (either because it is missing, or because it is a part of a bigger message
192 /// that is not fully available yet).
193 int32_t getFirstNonreadSeqNo() const;
194
195 /// Get information on packets available to be read.
196 /// @returns a pair of sequence numbers (first available; first unavailable).
197 ///
198 /// @note CSeqNo::seqoff(first, second) is 0 if nothing to read.
199 std::pair<int, int> getAvailablePacketsRange() const;
200
201 size_t countReadable() const;
202
203 bool empty() const
204 {
205 return (m_iMaxPosOff == 0);
206 }
207
208 /// Returns the currently used number of cells, including
209 /// gaps with empty cells, or in other words, the distance
210 /// between the initial position and the youngest received packet.
211 size_t size() const
212 {
213 return m_iMaxPosOff;
214 }
215
216 // Returns true if the buffer is full. Requires locking.
217 bool full() const
218 {
219 return size() == capacity();
220 }
221
222 /// Return buffer capacity.
223 /// One slot had to be empty in order to tell the difference between "empty buffer" and "full buffer".
224 /// E.g. m_iFirstNonreadPos would again point to m_iStartPos if m_szSize entries are added continuously.
225 /// TODO: Old receiver buffer capacity returns the actual size. Check for conflicts.
226 size_t capacity() const
227 {
228 return m_szSize - 1;
229 }
230
231 int64_t getDrift() const { return m_tsbpd.drift(); }
232
233 // TODO: make thread safe?
234 int debugGetSize() const
235 {
236 return getRcvDataSize();
237 }
238
239 /// Zero time to include all available packets.
240 /// TODO: Rename to 'canRead`.
241 bool isRcvDataReady(time_point time_now = time_point()) const;
242
243 int getRcvAvgDataSize(int& bytes, int& timespan);
244 void updRcvAvgDataSize(const time_point& now);
245
246 unsigned getRcvAvgPayloadSize() const { return m_uAvgPayloadSz; }
247
248 void getInternalTimeBase(time_point& w_timebase, bool& w_wrp, duration& w_udrift)
249 {
250 return m_tsbpd.getInternalTimeBase(w_timebase, w_wrp, w_udrift);
251 }
252
253 public: // Used for testing
254 /// Peek unit in position of seqno
255 const CUnit* peek(int32_t seqno);
256
257 private:
258 inline int incPos(int pos, int inc = 1) const { return (pos + inc) % m_szSize; }
259 inline int decPos(int pos) const { return (pos - 1) >= 0 ? (pos - 1) : int(m_szSize - 1); }
260 inline int offPos(int pos1, int pos2) const { return (pos2 >= pos1) ? (pos2 - pos1) : int(m_szSize + pos2 - pos1); }
261
262 /// @brief Compares the two positions in the receiver buffer relative to the starting position.
263 /// @param pos2 a position in the receiver buffer.
264 /// @param pos1 a position in the receiver buffer.
265 /// @return a positive value if pos2 is ahead of pos1; a negative value, if pos2 is behind pos1; otherwise returns 0.
266 inline int cmpPos(int pos2, int pos1) const
267 {
268 // XXX maybe not the best implementation, but this keeps up to the rule.
269 // Maybe use m_iMaxPosOff to ensure a position is not behind the m_iStartPos.
270 const int off1 = pos1 >= m_iStartPos ? pos1 - m_iStartPos : pos1 + (int)m_szSize - m_iStartPos;
271 const int off2 = pos2 >= m_iStartPos ? pos2 - m_iStartPos : pos2 + (int)m_szSize - m_iStartPos;
272
273 return off2 - off1;
274 }
275
276 // NOTE: Assumes that pUnit != NULL
277 CPacket& packetAt(int pos) { return m_entries[pos].pUnit->m_Packet; }
278 const CPacket& packetAt(int pos) const { return m_entries[pos].pUnit->m_Packet; }
279
280 private:
281 void countBytes(int pkts, int bytes);
282 void updateNonreadPos();
283 void releaseUnitInPos(int pos);
284
285 /// @brief Drop a unit from the buffer.
286 /// @param pos position in the m_entries of the unit to drop.
287 /// @return false if nothing to drop, true if the unit was dropped successfully.
288 bool dropUnitInPos(int pos);
289
290 /// Release entries following the current buffer position if they were already
291 /// read out of order (EntryState_Read) or dropped (EntryState_Drop).
292 void releaseNextFillerEntries();
293
294 bool hasReadableInorderPkts() const { return (m_iFirstNonreadPos != m_iStartPos); }
295
296 /// Find position of the last packet of the message.
297 int findLastMessagePkt();
298
299 /// Scan for availability of out of order packets.
300 void onInsertNotInOrderPacket(int insertpos);
301 // Check if m_iFirstReadableOutOfOrder is still readable.
302 bool checkFirstReadableOutOfOrder();
303 void updateFirstReadableOutOfOrder();
304 int scanNotInOrderMessageRight(int startPos, int msgNo) const;
305 int scanNotInOrderMessageLeft(int startPos, int msgNo) const;
306
307 typedef bool copy_to_dst_f(char* data, int len, int dst_offset, void* arg);
308
309 /// Read acknowledged data directly into file.
310 /// @param [in] ofs C++ file stream.
311 /// @param [in] len expected length of data to write into the file.
312 /// @return size of data read.
313 int readBufferTo(int len, copy_to_dst_f funcCopyToDst, void* arg);
314
315 /// @brief Estimate timespan of the stored packets (acknowledged and unacknowledged).
316 /// @return timespan in milliseconds
317 int getTimespan_ms() const;
318
319 private:
320 // TODO: Call makeUnitTaken upon assignment, and makeUnitFree upon clearing.
321 // TODO: CUnitPtr is not in use at the moment, but may be a smart pointer.
322 // class CUnitPtr
323 // {
324 // public:
325 // void operator=(CUnit* pUnit)
326 // {
327 // if (m_pUnit != NULL)
328 // {
329 // // m_pUnitQueue->makeUnitFree(m_entries[i].pUnit);
330 // }
331 // m_pUnit = pUnit;
332 // }
333 // private:
334 // CUnit* m_pUnit;
335 // };
336
337 enum EntryStatus
338 {
339 EntryState_Empty, //< No CUnit record.
340 EntryState_Avail, //< Entry is available for reading.
341 EntryState_Read, //< Entry has already been read (out of order).
342 EntryState_Drop //< Entry has been dropped.
343 };
344 struct Entry
345 {
346 Entry()
347 : pUnit(NULL)
348 , status(EntryState_Empty)
349 {}
350
351 CUnit* pUnit;
352 EntryStatus status;
353 };
354
355 typedef FixedArray<Entry> entries_t;
356 entries_t m_entries;
357
358 const size_t m_szSize; // size of the array of units (buffer)
359 CUnitQueue* m_pUnitQueue; // the shared unit queue
360
361 int m_iStartSeqNo;
362 int m_iStartPos; // the head position for I/O (inclusive)
363 int m_iFirstNonreadPos; // First position that can't be read (<= m_iLastAckPos)
364 int m_iMaxPosOff; // the furthest data position
365 int m_iNotch; // the starting read point of the first unit
366
367 size_t m_numOutOfOrderPackets; // The number of stored packets with "inorder" flag set to false
368 int m_iFirstReadableOutOfOrder; // In case of out ouf order packet, points to a position of the first such packet to
369 // read
370 bool m_bPeerRexmitFlag; // Needed to read message number correctly
371 const bool m_bMessageAPI; // Operation mode flag: message or stream.
372
373 public: // TSBPD public functions
374 /// Set TimeStamp-Based Packet Delivery Rx Mode
375 /// @param [in] timebase localtime base (uSec) of packet time stamps including buffering delay
376 /// @param [in] wrap Is in wrapping period
377 /// @param [in] delay agreed TsbPD delay
378 ///
379 /// @return 0
380 void setTsbPdMode(const time_point& timebase, bool wrap, duration delay);
381
382 void setPeerRexmitFlag(bool flag) { m_bPeerRexmitFlag = flag; }
383
384 void applyGroupTime(const time_point& timebase, bool wrp, uint32_t delay, const duration& udrift);
385
386 void applyGroupDrift(const time_point& timebase, bool wrp, const duration& udrift);
387
388 bool addRcvTsbPdDriftSample(uint32_t usTimestamp, const time_point& tsPktArrival, int usRTTSample);
389
390 time_point getPktTsbPdTime(uint32_t usPktTimestamp) const;
391
392 time_point getTsbPdTimeBase(uint32_t usPktTimestamp) const;
393 void updateTsbPdTimeBase(uint32_t usPktTimestamp);
394
395 bool isTsbPd() const { return m_tsbpd.isEnabled(); }
396
397 /// Form a string of the current buffer fullness state.
398 /// number of packets acknowledged, TSBPD readiness, etc.
399 std::string strFullnessState(int iFirstUnackSeqNo, const time_point& tsNow) const;
400
401 private:
402 CTsbpdTime m_tsbpd;
403
404 private: // Statistics
405 AvgBufSize m_mavg;
406
407 // TODO: m_BytesCountLock is probably not needed as the buffer has to be protected from simultaneous access.
408 mutable sync::Mutex m_BytesCountLock; // used to protect counters operations
409 int m_iBytesCount; // Number of payload bytes in the buffer
410 int m_iPktsCount; // Number of payload bytes in the buffer
411 unsigned m_uAvgPayloadSz; // Average payload size for dropped bytes estimation
412 };
413
414 } // namespace srt
415
416 #endif // INC_SRT_BUFFER_RCV_H