A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
queue-size.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Universita' degli Studi di Napoli Federico II
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Stefano Avallone <stavallo@unina.it>
7 */
8
9#ifndef QUEUE_SIZE_H
10#define QUEUE_SIZE_H
11
12#include "ns3/abort.h"
13#include "ns3/attribute-helper.h"
14#include "ns3/attribute.h"
15
16#include <iostream>
17#include <string>
18
19namespace ns3
20{
21
22/**
23 * @ingroup network
24 * @defgroup queuesize Queue size
25 */
26
27/**
28 * @ingroup queuesize
29 * @brief Enumeration of the operating modes of queues.
30 *
31 */
33{
34 PACKETS, /**< Use number of packets for queue size */
35 BYTES, /**< Use number of bytes for queue size */
36};
37
38/**
39 * @ingroup queuesize
40 * @brief Class for representing queue sizes
41 *
42 * Allows for natural and familiar use of queue sizes. Allows construction
43 * from strings, natural sum e.g.:
44 * @code
45 * QueueSize x("7kB");
46 * Ptr<Packet> p = Create<Packet> (1000);
47 * QueueSize y = x + p; // 8kB
48 * @endcode
49 * This class also supports the regular comparison operators \c <, \c >,
50 * \c <=, \c >=, \c ==, and \c !=
51 *
52 * Queue size specifiers consist of
53 * * A numeric value,
54 * * An optional multiplier prefix and
55 * * A unit.
56 *
57 * Whitespace is allowed but not required between the numeric value and
58 * multiplier or unit.
59 *
60 * Supported multiplier prefixes:
61 *
62 * | Prefix | Value |
63 * | :------- | ----------: |
64 * | "k", "K" | 1000 |
65 * | "Ki" | 1024 |
66 * | "M" | 1000000 |
67 * | "Mi" | 1024 Ki |
68 *
69 * Supported unit strings:
70 *
71 * | Symbol | Meaning |
72 * | :------- | :---------- |
73 * | "B" | 8-bit bytes |
74 * | "p" | packets |
75 *
76 * Examples:
77 * * "56kB" = 56,000 bytes
78 * * "128 kB" = 128,000 bytes
79 * * "8KiB" = 8,192 bytes
80 * * "1000p" = 1,000 packets
81 *
82 * @see attribute_QueueSize
83 */
85{
86 public:
87 QueueSize();
88 /**
89 * @brief Integer constructor
90 *
91 * Construct a queue size from a mode and a value.
92 * @param unit whether the value is expressed in terms of packets or bytes
93 * @param value the value
94 */
95 QueueSize(QueueSizeUnit unit, uint32_t value);
96 /**
97 * @brief String constructor
98 *
99 * Construct a queue size from a string. Many different unit strings are supported
100 * Supported unit strings:
101 * B, p \n
102 * kB, KB, KiB, kp, Kp, Kip \n
103 * MB, MiB, Mp, Mip \n
104 *
105 * Examples:
106 * "56kB" = 56,000 bytes
107 * "128 kB" = 128,000 bytes
108 * "8KiB" = 8,192 bytes
109 * "1000p" = 1,000 packets
110 *
111 * @param size string representing the size
112 */
113 QueueSize(std::string size);
114
115 /**
116 * @return true if this size is less than rhs
117 *
118 * @param rhs the queue size to compare to this queue size
119 */
120 bool operator<(const QueueSize& rhs) const;
121
122 /**
123 * @return true if this size is less than or equal to rhs
124 *
125 * @param rhs the queue size to compare to this queue size
126 */
127 bool operator<=(const QueueSize& rhs) const;
128
129 /**
130 * @return true if this size is greater than rhs
131 *
132 * @param rhs the queue size to compare to this queue size
133 */
134 bool operator>(const QueueSize& rhs) const;
135
136 /**
137 * @return true if this size is greater than or equal to rhs
138 *
139 * @param rhs the queue size to compare to this queue size
140 */
141 bool operator>=(const QueueSize& rhs) const;
142
143 /**
144 * @return true if this size is equal to rhs
145 *
146 * @param rhs the queue size to compare to this queue size
147 */
148 bool operator==(const QueueSize& rhs) const;
149
150 /**
151 * @return true if this size is not equal to rhs
152 *
153 * @param rhs the queue size to compare to this queue size
154 */
155 bool operator!=(const QueueSize& rhs) const;
156
157 /**
158 * Get the underlying unit
159 * @return The underlying unit
160 */
161 QueueSizeUnit GetUnit() const;
162
163 /**
164 * Get the underlying value
165 * @return The underlying value
166 */
167 uint32_t GetValue() const;
168
169 private:
170 /**
171 * @brief Parse a string representing a QueueSize
172 *
173 * Allowed unit representations include all combinations of
174 *
175 * * An SI prefix: k, K, M
176 * * Bytes (8 bits) or packets
177 *
178 * @param [in] s The string representation, including unit
179 * @param [in,out] unit The location to put the unit.
180 * @param [in,out] value The location to put the value, in bytes or packets.
181 * @return true if parsing was successful.
182 */
183 static bool DoParse(const std::string s, QueueSizeUnit* unit, uint32_t* value);
184
185 // Uses DoParse
186 friend std::istream& operator>>(std::istream& is, QueueSize& size);
187
189 uint32_t m_value; //!< queue size [bytes or packets]
190};
191
192/**
193 * @brief Stream insertion operator.
194 *
195 * @param os the stream
196 * @param size the queue size
197 * @returns a reference to the stream
198 */
199std::ostream& operator<<(std::ostream& os, const QueueSize& size);
200
201/**
202 * @brief Stream extraction operator.
203 *
204 * @param is the stream
205 * @param size the queue size
206 * @returns a reference to the stream
207 */
208std::istream& operator>>(std::istream& is, QueueSize& size);
209
211
212/**
213 * Increase the queue size by a packet size, if the queue size is in bytes,
214 * or by one, otherwise.
215 *
216 * @param lhs queue size
217 * @param rhs packet
218 * @return the queue size increased by the packet size
219 */
220template <typename Item>
221QueueSize operator+(const QueueSize& lhs, const Ptr<Item>& rhs);
222/**
223 * Increase the queue size by a packet size, if the queue size is in bytes,
224 * or by one, otherwise.
225 *
226 * @param lhs packet
227 * @param rhs queue size
228 * @return the queue size increased by the packet size
229 */
230template <typename Item>
231QueueSize operator+(const Ptr<Item>& lhs, const QueueSize& rhs);
232
233/**
234 * Decrease the queue size by a packet size, if the queue size is in bytes,
235 * or by one, otherwise.
236 *
237 * @param lhs queue size
238 * @param rhs packet
239 * @return the queue size decreased by the packet size
240 */
241template <typename Item>
242QueueSize operator-(const QueueSize& lhs, const Ptr<Item>& rhs);
243/**
244 * Decrease the queue size by a packet size, if the queue size is in bytes,
245 * or by one, otherwise.
246 *
247 * @param lhs packet
248 * @param rhs queue size
249 * @return the queue size decreased by the packet size
250 */
251template <typename Item>
252QueueSize operator-(const Ptr<Item>& lhs, const QueueSize& rhs);
253
254/**
255 * Implementation of the templates declared above.
256 */
257
258template <typename Item>
260operator+(const QueueSize& lhs, const Ptr<Item>& rhs)
261{
262 if (lhs.GetUnit() == QueueSizeUnit::PACKETS)
263 {
264 return QueueSize(lhs.GetUnit(), lhs.GetValue() + 1);
265 }
266 if (lhs.GetUnit() == QueueSizeUnit::BYTES)
267 {
268 return QueueSize(lhs.GetUnit(), lhs.GetValue() + rhs->GetSize());
269 }
270 NS_FATAL_ERROR("Unknown queue size mode");
271}
272
273template <typename Item>
274QueueSize
275operator+(const Ptr<Item>& lhs, const QueueSize& rhs)
276{
277 if (rhs.GetUnit() == QueueSizeUnit::PACKETS)
278 {
279 return QueueSize(rhs.GetUnit(), rhs.GetValue() + 1);
280 }
281 if (rhs.GetUnit() == QueueSizeUnit::BYTES)
282 {
283 return QueueSize(rhs.GetUnit(), rhs.GetValue() + lhs->GetSize());
284 }
285 NS_FATAL_ERROR("Unknown queue size mode");
286}
287
288template <typename Item>
289QueueSize
290operator-(const QueueSize& lhs, const Ptr<Item>& rhs)
291{
292 if (lhs.GetUnit() == QueueSizeUnit::PACKETS)
293 {
294 NS_ABORT_IF(lhs.GetValue() < 1);
295 return QueueSize(lhs.GetUnit(), lhs.GetValue() - 1);
296 }
297 if (lhs.GetUnit() == QueueSizeUnit::BYTES)
298 {
299 NS_ABORT_IF(lhs.GetValue() < rhs->GetSize());
300 return QueueSize(lhs.GetUnit(), lhs.GetValue() - rhs->GetSize());
301 }
302 NS_FATAL_ERROR("Unknown queue size mode");
303}
304
305template <typename Item>
306QueueSize
307operator-(const Ptr<Item>& lhs, const QueueSize& rhs)
308{
309 if (rhs.GetUnit() == QueueSizeUnit::PACKETS)
310 {
311 NS_ABORT_IF(rhs.GetValue() < 1);
312 return QueueSize(rhs.GetUnit(), rhs.GetValue() - 1);
313 }
314 if (rhs.GetUnit() == QueueSizeUnit::BYTES)
315 {
316 NS_ABORT_IF(rhs.GetValue() < lhs->GetSize());
317 return QueueSize(rhs.GetUnit(), rhs.GetValue() - lhs->GetSize());
318 }
319 NS_FATAL_ERROR("Unknown queue size mode");
320}
321
322} // namespace ns3
323
324#endif /* QUEUE_SIZE_H */
Smart pointer class similar to boost::intrusive_ptr.
Class for representing queue sizes.
Definition queue-size.h:85
bool operator>(const QueueSize &rhs) const
friend std::istream & operator>>(std::istream &is, QueueSize &size)
Stream extraction operator.
bool operator<(const QueueSize &rhs) const
bool operator<=(const QueueSize &rhs) const
QueueSizeUnit GetUnit() const
Get the underlying unit.
bool operator!=(const QueueSize &rhs) const
uint32_t m_value
queue size [bytes or packets]
Definition queue-size.h:189
bool operator>=(const QueueSize &rhs) const
bool operator==(const QueueSize &rhs) const
QueueSizeUnit m_unit
unit
Definition queue-size.h:188
static bool DoParse(const std::string s, QueueSizeUnit *unit, uint32_t *value)
Parse a string representing a QueueSize.
Definition queue-size.cc:22
uint32_t GetValue() const
Get the underlying value.
#define ATTRIBUTE_HELPER_HEADER(type)
Declare the attribute value, accessor and checkers for class type
#define NS_FATAL_ERROR(msg)
Report a fatal error with a message and terminate.
#define NS_ABORT_IF(cond)
Abnormal program termination if a condition is true.
Definition abort.h:65
int64x64_t operator-(const int64x64_t &lhs, const int64x64_t &rhs)
Subtraction operator.
Definition int64x64.h:91
int64x64_t operator+(const int64x64_t &lhs, const int64x64_t &rhs)
Addition operator.
Definition int64x64.h:76
QueueSizeUnit
Enumeration of the operating modes of queues.
Definition queue-size.h:33
@ BYTES
Use number of bytes for queue size.
Definition queue-size.h:35
@ PACKETS
Use number of packets for queue size.
Definition queue-size.h:34
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
std::istream & operator>>(std::istream &is, Angles &a)
Definition angles.cc:172