| 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 |