Debian Codegraph @

srtcore/buffer_snd.h

raw
1 /*
2 * SRT - Secure, Reliable, Transport
3 * Copyright (c) 2018 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 /*****************************************************************************
12 Copyright (c) 2001 - 2009, The Board of Trustees of the University of Illinois.
13 All rights reserved.
14
15 Redistribution and use in source and binary forms, with or without
16 modification, are permitted provided that the following conditions are
17 met:
18
19 * Redistributions of source code must retain the above
20 copyright notice, this list of conditions and the
21 following disclaimer.
22
23 * Redistributions in binary form must reproduce the
24 above copyright notice, this list of conditions
25 and the following disclaimer in the documentation
26 and/or other materials provided with the distribution.
27
28 * Neither the name of the University of Illinois
29 nor the names of its contributors may be used to
30 endorse or promote products derived from this
31 software without specific prior written permission.
32
33 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
34 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
35 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
36 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
37 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
38 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
39 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
40 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
41 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
42 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
43 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44 *****************************************************************************/
45
46 /*****************************************************************************
47 written by
48 Yunhong Gu, last updated 05/05/2009
49 modified by
50 Haivision Systems Inc.
51 *****************************************************************************/
52
53 #ifndef INC_SRT_BUFFER_SND_H
54 #define INC_SRT_BUFFER_SND_H
55
56 #include "srt.h"
57 #include "packet.h"
58 #include "buffer_tools.h"
59
60 // The notation used for "circular numbers" in comments:
61 // The "cicrular numbers" are numbers that when increased up to the
62 // maximum become zero, and similarly, when the zero value is decreased,
63 // it turns into the maximum value minus one. This wrapping works the
64 // same for adding and subtracting. Circular numbers cannot be multiplied.
65
66 // Operations done on these numbers are marked with additional % character:
67 // a %> b : a is later than b
68 // a ++% (++%a) : shift a by 1 forward
69 // a +% b : shift a by b
70 // a == b : equality is same as for just numbers
71
72 namespace srt {
73
74 class CSndBuffer
75 {
76 typedef sync::steady_clock::time_point time_point;
77 typedef sync::steady_clock::duration duration;
78
79 public:
80 // XXX There's currently no way to access the socket ID set for
81 // whatever the buffer is currently working for. Required to find
82 // some way to do this, possibly by having a "reverse pointer".
83 // Currently just "unimplemented".
84 std::string CONID() const { return ""; }
85
86 /// @brief CSndBuffer constructor.
87 /// @param size initial number of blocks (each block to store one packet payload).
88 /// @param maxpld maximum packet payload (including auth tag).
89 /// @param authtag auth tag length in bytes (16 for GCM, 0 otherwise).
90 CSndBuffer(int ip_family, int size, int maxpld, int authtag);
91 ~CSndBuffer();
92
93 public:
94 /// Insert a user buffer into the sending list.
95 /// For @a w_mctrl the following fields are used:
96 /// INPUT:
97 /// - msgttl: timeout for retransmitting the message, if lost
98 /// - inorder: request to deliver the message in order of sending
99 /// - srctime: local time as a base for packet's timestamp (0 if unused)
100 /// - pktseq: sequence number to be stamped on the packet (-1 if unused)
101 /// - msgno: message number to be stamped on the packet (-1 if unused)
102 /// OUTPUT:
103 /// - srctime: local time stamped on the packet (same as input, if input wasn't 0)
104 /// - pktseq: sequence number to be stamped on the next packet
105 /// - msgno: message number stamped on the packet
106 /// @param [in] data pointer to the user data block.
107 /// @param [in] len size of the block.
108 /// @param [inout] w_mctrl Message control data
109 SRT_ATTR_EXCLUDES(m_BufLock)
110 void addBuffer(const char* data, int len, SRT_MSGCTRL& w_mctrl);
111
112 /// Read a block of data from file and insert it into the sending list.
113 /// @param [in] ifs input file stream.
114 /// @param [in] len size of the block.
115 /// @return actual size of data added from the file.
116 SRT_ATTR_EXCLUDES(m_BufLock)
117 int addBufferFromFile(std::fstream& ifs, int len);
118
119 // Special values that can be returned by readData.
120 static const int READ_NONE = 0;
121 static const int READ_DROP = -1;
122
123 /// Find data position to pack a DATA packet from the furthest reading point.
124 /// @param [out] packet the packet to read.
125 /// @param [out] origintime origin time stamp of the message
126 /// @param [in] kflags Odd|Even crypto key flag
127 /// @param [out] seqnoinc the number of packets skipped due to TTL, so that seqno should be incremented.
128 /// @return Actual length of data read.
129 SRT_ATTR_EXCLUDES(m_BufLock)
130 int readData(CPacket& w_packet, time_point& w_origintime, int kflgs, int& w_seqnoinc);
131
132 /// Peek an information on the next original data packet to send.
133 /// @return origin time stamp of the next packet; epoch start time otherwise.
134 SRT_ATTR_EXCLUDES(m_BufLock)
135 time_point peekNextOriginal() const;
136
137 struct DropRange
138 {
139 static const size_t BEGIN = 0, END = 1;
140 int32_t seqno[2];
141 int32_t msgno;
142 };
143 /// Find data position to pack a DATA packet for a retransmission.
144 /// IMPORTANT: @a packet is [in,out] because it is expected to get set
145 /// the sequence number of the packet expected to be sent next. The sender
146 /// buffer normally doesn't handle sequence numbers and the consistency
147 /// between the sequence number of a packet already sent and kept in the
148 /// buffer is achieved by having the sequence number recorded in the
149 /// CUDT::m_iSndLastDataAck field that should represent the oldest packet
150 /// still in the buffer.
151 /// @param [in] offset offset from the last ACK point (backward sequence number difference)
152 /// @param [in,out] w_packet storage for the packet, preinitialized with sequence number
153 /// @param [out] w_origintime origin time stamp of the message
154 /// @param [out] w_drop the drop information in case when dropping is to be done instead
155 /// @retval >0 Length of the data read.
156 /// @retval READ_NONE No data available or @a offset points out of the buffer occupied space.
157 /// @retval READ_DROP The call requested data drop due to TTL exceeded, to be handled first.
158 SRT_ATTR_EXCLUDES(m_BufLock)
159 int readData(const int offset, CPacket& w_packet, time_point& w_origintime, DropRange& w_drop);
160
161 /// Get the time of the last retransmission (if any) of the DATA packet.
162 /// @param [in] offset offset from the last ACK point (backward sequence number difference)
163 ///
164 /// @return Last time of the last retransmission event for the corresponding DATA packet.
165 SRT_ATTR_EXCLUDES(m_BufLock)
166 time_point getPacketRexmitTime(const int offset);
167
168 /// Update the ACK point and may release/unmap/return the user data according to the flag.
169 /// @param [in] offset number of packets acknowledged.
170 int32_t getMsgNoAt(const int offset);
171
172 void ackData(int offset);
173
174 /// Read size of data still in the sending list.
175 /// @return Current size of the data in the sending list.
176 int getCurrBufSize() const;
177
178 SRT_ATTR_EXCLUDES(m_BufLock)
179 int dropLateData(int& bytes, int32_t& w_first_msgno, const time_point& too_late_time);
180
181 void updAvgBufSize(const time_point& time);
182 int getAvgBufSize(int& bytes, int& timespan);
183 int getCurrBufSize(int& bytes, int& timespan) const;
184
185
186 /// Het maximum payload length per packet.
187 int getMaxPacketLen() const;
188
189 /// @brief Count the number of required packets to store the payload (message).
190 /// @param iPldLen the length of the payload to check.
191 /// @return the number of required data packets.
192 int countNumPacketsRequired(int iPldLen) const;
193
194 /// @brief Count the number of required packets to store the payload (message).
195 /// @param iPldLen the length of the payload to check.
196 /// @param iMaxPktLen the maximum payload length of the packet (the value returned from getMaxPacketLen()).
197 /// @return the number of required data packets.
198 int countNumPacketsRequired(int iPldLen, int iMaxPktLen) const;
199
200 /// @brief Get the buffering delay of the oldest message in the buffer.
201 /// @return the delay value.
202 SRT_ATTR_EXCLUDES(m_BufLock)
203 duration getBufferingDelay(const time_point& tnow) const;
204
205 uint64_t getInRatePeriod() const { return m_rateEstimator.getInRatePeriod(); }
206
207 /// Retrieve input bitrate in bytes per second
208 int getInputRate() const { return m_rateEstimator.getInputRate(); }
209
210 void resetInputRateSmpPeriod(bool disable = false) { m_rateEstimator.resetInputRateSmpPeriod(disable); }
211
212 const CRateEstimator& getRateEstimator() const { return m_rateEstimator; }
213
214 void setRateEstimator(const CRateEstimator& other) { m_rateEstimator = other; }
215
216 private:
217 void increase();
218
219 private:
220 mutable sync::Mutex m_BufLock; // used to synchronize buffer operation
221
222 struct Block
223 {
224 char* m_pcData; // pointer to the data block
225 int m_iLength; // payload length of the block (excluding auth tag).
226
227 int32_t m_iMsgNoBitset; // message number
228 int32_t m_iSeqNo; // sequence number for scheduling
229 time_point m_tsOriginTime; // block origin time (either provided from above or equals the time a message was submitted for sending.
230 time_point m_tsRexmitTime; // packet retransmission time
231 int m_iTTL; // time to live (milliseconds)
232
233 Block* m_pNext; // next block
234
235 int32_t getMsgSeq()
236 {
237 // NOTE: this extracts message ID with regard to REXMIT flag.
238 // This is valid only for message ID that IS GENERATED in this instance,
239 // not provided by the peer. This can be otherwise sent to the peer - it doesn't matter
240 // for the peer that it uses LESS bits to represent the message.
241 return m_iMsgNoBitset & MSGNO_SEQ::mask;
242 }
243
244 } * m_pBlock, *m_pFirstBlock, *m_pCurrBlock, *m_pLastBlock;
245
246 // m_pBlock: The head pointer
247 // m_pFirstBlock: The first block
248 // m_pCurrBlock: The current block
249 // m_pLastBlock: The last block (if first == last, buffer is empty)
250
251 struct Buffer
252 {
253 char* m_pcData; // buffer
254 int m_iSize; // size
255 Buffer* m_pNext; // next buffer
256 } * m_pBuffer; // physical buffer
257
258 int32_t m_iNextMsgNo; // next message number
259
260 int m_iSize; // buffer size (number of packets)
261 const int m_iBlockLen; // maximum length of a block holding packet payload and AUTH tag (excluding packet header).
262 const int m_iAuthTagSize; // Authentication tag size (if GCM is enabled).
263
264 // NOTE: This is atomic AND under lock because the function getCurrBufSize()
265 // is returning it WITHOUT locking. Modification, however, must stay under
266 // a lock.
267 sync::atomic<int> m_iCount; // number of used blocks
268
269 int m_iBytesCount; // number of payload bytes in queue
270 time_point m_tsLastOriginTime;
271
272 AvgBufSize m_mavg;
273 CRateEstimator m_rateEstimator;
274
275 private:
276 CSndBuffer(const CSndBuffer&);
277 CSndBuffer& operator=(const CSndBuffer&);
278 };
279
280 } // namespace srt
281
282 #endif