1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 2 // 3 // Copyright (c) 2006 Georgia Tech Research Corporation 4 // 5 // This program is free software; you can redistribute it and/or modify 6 // it under the terms of the GNU General Public License version 2 as 7 // published by the Free Software Foundation; 8 // 9 // This program is distributed in the hope that it will be useful, 10 // but WITHOUT ANY WARRANTY; without even the implied warranty of 11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 // GNU General Public License for more details. 13 // 14 // You should have received a copy of the GNU General Public License 15 // along with this program; if not, write to the Free Software 16 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 17 // 18 // Author: Rajib Bhattacharjea<raj.b@gatech.edu> 19 // 20 21 #ifndef DATA_RATE_H 22 #define DATA_RATE_H 23 24 #include <string> 25 #include <iostream> 26 #include <stdint.h> 27 #include "ns3/nstime.h" 28 #include "ns3/attribute.h" 29 #include "ns3/attribute-helper.h" 30 #include "ns3/deprecated.h" 31 32 namespace ns3 { 33 34 /** 35 * \ingroup network 36 * \defgroup datarate Data Rate 37 */ 38 /** 39 * \ingroup datarate 40 * \brief Class for representing data rates 41 * 42 * Allows for natural and familiar use of data rates. Allows construction 43 * from strings, natural multiplication e.g.: 44 * \code 45 * DataRate x("56kbps"); 46 * double nBits = x*ns3::Seconds (19.2); 47 * uint32_t nBytes = 20; 48 * Time txtime = x.CalculateBytesTxTime (nBytes); 49 * \endcode 50 * This class also supports the regular comparison operators \c <, \c >, 51 * \c <=, \c >=, \c ==, and \c != 52 * 53 * Data rate specifiers consist of 54 * * A numeric value, 55 * * An optional multiplier prefix and 56 * * A unit. 57 * 58 * Whitespace is allowed but not required between the numeric value and 59 * multipler or unit. 60 * 61 * Supported multiplier prefixes: 62 * 63 * | Prefix | Value | 64 * | :------- | ----------: | 65 * | "k", "K" | 1000 | 66 * | "Ki" | 1024 | 67 * | "M" | 1000000 | 68 * | "Mi" | 1024 Ki | 69 * | "G" | 10^9 | 70 * | "Gi " | 1024 Mi | 71 * 72 * Supported unit strings: 73 * 74 * | Symbol | Meaning | 75 * | :------- | :---------- | 76 * | "b" | bits | 77 * | "B" | 8-bit bytes | 78 * | "s", "/s"| per second | 79 * 80 * Examples: 81 * * "56kbps" = 56,000 bits/s 82 * * "128 kb/s" = 128,000 bits/s 83 * * "8Kib/s" = 1 KiB/s = 8192 bits/s 84 * * "1kB/s" = 8000 bits/s 85 * 86 * \see attribute_DataRate 87 */ 88 class DataRate 89 { 90 public: 91 DataRate (); 92 /** 93 * \brief Integer constructor 94 * 95 * Construct a data rate from an integer. This class only supports positive 96 * integer data rates in units of bits/s, meaning 1bit/s is the smallest 97 * non-trivial bitrate available. 98 * \param bps bit/s value 99 */ 100 DataRate (uint64_t bps); 101 /** 102 * \brief String constructor 103 * 104 * Construct a data rate from a string. Many different unit strings are supported 105 * Supported unit strings: 106 * bps, b/s, Bps, B/s \n 107 * kbps, kb/s, Kbps, Kb/s, kBps, kB/s, KBps, KB/s, Kib/s, KiB/s \n 108 * Mbps, Mb/s, MBps, MB/s, Mib/s, MiB/s \n 109 * Gbps, Gb/s, GBps, GB/s, Gib/s, GiB/s \n 110 * 111 * Examples: 112 * "56kbps" = 56,000 bits/s \n 113 * "128 kb/s" = 128,000 bits/s \n 114 * "8Kib/s" = 1 KiB/s = 8192 bits/s \n 115 * "1kB/s" = 8000 bits/s 116 * 117 * \param rate string representing the desired rate 118 */ 119 DataRate (std::string rate); 120 121 /** 122 * \return the DataRate representing the sum of this object with rhs 123 * 124 * \param rhs the DataRate to add to this DataRate 125 */ 126 DataRate operator + (DataRate rhs); 127 128 /** 129 * \return the DataRate representing the sum of this object with rhs 130 * 131 * \param rhs the DataRate to add to this DataRate 132 */ 133 DataRate& operator += (DataRate rhs); 134 135 /** 136 * \return the DataRate representing the difference of this object with rhs 137 * 138 * \param rhs the DataRate to subtract from this DataRate 139 */ 140 DataRate operator - (DataRate rhs); 141 142 /** 143 * \return the DataRate representing the difference of this object with rhs 144 * 145 * \param rhs the DataRate to subtract from this DataRate 146 */ 147 DataRate& operator -= (DataRate rhs); 148 149 /** 150 * \brief Scales the DataRate 151 * 152 * Multiplies with double and is re-casted to an int 153 * 154 * \return DataRate object representing the product of this object with rhs 155 * 156 * \param rhs the double to multiply to this datarate 157 */ 158 DataRate operator * (double rhs); 159 160 /** 161 * \brief Scales the DataRate 162 * 163 * Multiplies with double and is re-casted to an int 164 * 165 * \return DataRate object representing the product of this object with rhs 166 * 167 * \param rhs the double to multipy to this datarate 168 */ 169 DataRate& operator *= (double rhs); 170 171 /** 172 * \brief Scales the DataRate 173 * 174 * \return DataRate object representing the product of this object with rhs 175 * 176 * \param rhs the uint64_t to multipy to this datarate 177 */ 178 DataRate operator * (uint64_t rhs); 179 180 /** 181 * \brief Scales the DataRate 182 * 183 * \return DataRate object representing the product of this object with rhs 184 * 185 * \param rhs the uint64_t to multipy to this datarate 186 */ 187 DataRate& operator *= (uint64_t rhs); 188 189 190 /** 191 * \return true if this rate is less than rhs 192 * 193 * \param rhs the datarate to compare to this datarate 194 */ 195 bool operator < (const DataRate& rhs) const; 196 197 /** 198 * \return true if this rate is less than or equal to rhs 199 * 200 * \param rhs the datarate to compare to this datarate 201 */ 202 bool operator <= (const DataRate& rhs) const; 203 204 /** 205 * \return true if this rate is greater than rhs 206 * 207 * \param rhs the datarate to compare to this datarate 208 */ 209 bool operator > (const DataRate& rhs) const; 210 211 /** 212 * \return true if this rate is greater than or equal to rhs 213 * 214 * \param rhs the datarate to compare to this datarate 215 */ 216 bool operator >= (const DataRate& rhs) const; 217 218 /** 219 * \return true if this rate is equal to rhs 220 * 221 * \param rhs the datarate to compare to this datarate 222 */ 223 bool operator == (const DataRate& rhs) const; 224 225 /** 226 * \return true if this rate is not equal to rhs 227 * 228 * \param rhs the datarate to compare to this datarate 229 */ 230 bool operator != (const DataRate& rhs) const; 231 232 /** 233 * \brief Calculate transmission time 234 * 235 * Calculates the transmission time at this data rate 236 * \param bytes The number of bytes (not bits) for which to calculate 237 * \return The transmission time for the number of bytes specified 238 */ 239 Time CalculateBytesTxTime (uint32_t bytes) const; 240 241 /** 242 * \brief Calculate transmission time 243 * 244 * Calculates the transmission time at this data rate 245 * \param bits The number of bits (not bytes) for which to calculate 246 * \return The transmission time for the number of bits specified 247 */ 248 Time CalculateBitsTxTime (uint32_t bits) const; 249 250 /** 251 * Get the underlying bitrate 252 * \return The underlying bitrate in bits per second 253 */ 254 uint64_t GetBitRate () const; 255 256 private: 257 258 /** 259 * \brief Parse a string representing a DataRate into an uint64_t 260 * 261 * Allowed unit representations include all combinations of 262 * 263 * * An SI prefix: k, K, M, G 264 * * Decimal or kibibit (as in "Kibps", meaning 1024 bps) 265 * * Bits or bytes (8 bits) 266 * * "bps" or "/s" 267 * 268 * \param [in] s The string representation, including unit 269 * \param [in,out] v The location to put the value, in bits/sec. 270 * \return true if parsing was successful. 271 */ 272 static bool DoParse (const std::string s, uint64_t *v); 273 274 // Uses DoParse 275 friend std::istream &operator >> (std::istream &is, DataRate &rate); 276 277 uint64_t m_bps; //!< data rate [bps] 278 }; 279 280 /** 281 * \brief Stream insertion operator. 282 * 283 * \param os the stream 284 * \param rate the data rate 285 * \returns a reference to the stream 286 */ 287 std::ostream &operator << (std::ostream &os, const DataRate &rate); 288 289 /** 290 * \brief Stream extraction operator. 291 * 292 * \param is the stream 293 * \param rate the data rate 294 * \returns a reference to the stream 295 */ 296 std::istream &operator >> (std::istream &is, DataRate &rate); 297 298 ATTRIBUTE_HELPER_HEADER (DataRate); 299 300 301 /** 302 * \brief Multiply datarate by a time value 303 * 304 * Calculates the number of bits that have been transmitted over a period of time 305 * \param lhs rate 306 * \param rhs time 307 * \return the number of bits over the period of time 308 */ 309 double operator* (const DataRate& lhs, const Time& rhs); 310 /** 311 * \brief Multiply time value by a data rate 312 * 313 * Calculates the number of bits that have been transmitted over a period of time 314 * \param lhs time 315 * \param rhs rate 316 * \return the number of bits over the period of time 317 */ 318 double operator* (const Time& lhs, const DataRate& rhs); 319 320 namespace TracedValueCallback { 321 322 /** 323 * \ingroup network 324 * TracedValue callback signature for DataRate 325 * 326 * \param [in] oldValue original value of the traced variable 327 * \param [in] newValue new value of the traced variable 328 */ 329 typedef void (* DataRate)(DataRate oldValue, 330 DataRate newValue); 331 332 } // namespace TracedValueCallback 333 334 } // namespace ns3 335 336 #endif /* DATA_RATE_H */ 337