LEFT | RIGHT |
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ | 1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ |
2 /* | 2 /* |
3 * Copyright (c) 2005,2006 INRIA | 3 * Copyright (c) 2005,2006 INRIA |
4 * | 4 * |
5 * This program is free software; you can redistribute it and/or modify | 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 | 6 * it under the terms of the GNU General Public License version 2 as |
7 * published by the Free Software Foundation; | 7 * published by the Free Software Foundation; |
8 * | 8 * |
9 * This program is distributed in the hope that it will be useful, | 9 * This program is distributed in the hope that it will be useful, |
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of | 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
(...skipping 184 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
195 * | 195 * |
196 * Implementing a new type of Tag requires roughly the same amount of | 196 * Implementing a new type of Tag requires roughly the same amount of |
197 * work and this work is described in the ns3::Tag API documentation. | 197 * work and this work is described in the ns3::Tag API documentation. |
198 * | 198 * |
199 * The performance aspects of the Packet API are discussed in· | 199 * The performance aspects of the Packet API are discussed in· |
200 * \ref packetperf | 200 * \ref packetperf |
201 */ | 201 */ |
202 class Packet : public SimpleRefCount<Packet> | 202 class Packet : public SimpleRefCount<Packet> |
203 { | 203 { |
204 public: | 204 public: |
205 Ptr<Packet> Copy (void) const; | |
206 | 205 |
207 /** | 206 /** |
208 * Create an empty packet with a new uid (as returned | 207 * Create an empty packet with a new uid (as returned |
209 * by getUid). | 208 * by getUid). |
210 */ | 209 */ |
211 Packet (); | 210 Packet (); |
212 Packet (const Packet &o); | 211 Packet (const Packet &o); |
213 Packet &operator = (const Packet &o);·· | 212 Packet &operator = (const Packet &o);·· |
214 /** | 213 /** |
215 * Create a packet with a zero-filled payload. | 214 * Create a packet with a zero-filled payload. |
216 * The memory necessary for the payload is not allocated: | 215 * The memory necessary for the payload is not allocated: |
217 * it will be allocated at any later point if you attempt | 216 * it will be allocated at any later point if you attempt |
218 * to fragment this packet or to access the zero-filled | 217 * to fragment this packet or to access the zero-filled |
219 * bytes. The packet is allocated with a new uid (as· | 218 * bytes. The packet is allocated with a new uid (as· |
220 * returned by getUid). | 219 * returned by getUid). |
221 *· | 220 *· |
222 * \param size the size of the zero-filled payload | 221 * \param size the size of the zero-filled payload |
223 */ | 222 */ |
224 Packet (uint32_t size); | 223 Packet (uint32_t size); |
225 /** | 224 /** |
226 * Create a packet with a zero-filled payload. | 225 * Create a new packet from the serialized buffer. This new packet· |
227 * The memory necessary for the payload is not allocated: | 226 * is identical to the serialized packet contained in the buffer· |
228 * it will be allocated at any later point if you attempt | 227 * and is magically deserialized for you |
229 * to fragment this packet or to access the zero-filled | |
230 * bytes. The packet is allocated with uid and mpiRank | |
231 *· | 228 *· |
232 * \param rank the MPI rank for this packet | 229 * \param buffer the serialized packet to be created |
233 * \param uid the unique id for this packet | 230 * \param size the size of the packet for deserialization |
234 * \param size the size of the zero-filled payload | 231 * \param magic allows packet deserialization;· |
235 * | 232 * asserts when set to false |
236 * This contructor is used for MPI simulations where· | 233 */ |
237 * it is important to keep the uid the same across· | 234 Packet (uint8_t const*buffer, uint32_t size, bool magic); |
238 * simulator boundaries. | |
239 */ | |
240 Packet (uint32_t mpiRank, uint32_t uid, uint32_t size); | |
241 /** | 235 /** |
242 * Create a packet with payload filled with the content | 236 * Create a packet with payload filled with the content |
243 * of this buffer. The input data is copied: the input | 237 * of this buffer. The input data is copied: the input |
244 * buffer is untouched. | 238 * buffer is untouched. |
245 * | 239 * |
246 * \param buffer the data to store in the packet. | 240 * \param buffer the data to store in the packet. |
247 * \param size the size of the input buffer. | 241 * \param size the size of the input buffer. |
248 */ | 242 */ |
249 Packet (uint8_t const*buffer, uint32_t size); | 243 Packet (uint8_t const*buffer, uint32_t size); |
250 /** | 244 /** |
(...skipping 104 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
355 /** | 349 /** |
356 * \param buffer a pointer to a byte buffer where the packet data· | 350 * \param buffer a pointer to a byte buffer where the packet data· |
357 * should be copied. | 351 * should be copied. |
358 * \param size the size of the byte buffer.· | 352 * \param size the size of the byte buffer.· |
359 * \returns the number of bytes read from the packet | 353 * \returns the number of bytes read from the packet |
360 * | 354 * |
361 * No more than \b size bytes will be copied by this function. | 355 * No more than \b size bytes will be copied by this function. |
362 */ | 356 */ |
363 uint32_t CopyData (uint8_t *buffer, uint32_t size) const; | 357 uint32_t CopyData (uint8_t *buffer, uint32_t size) const; |
364 | 358 |
| 359 /** |
| 360 * \param os pointer to output stream in which we want |
| 361 * to write the packet data. |
| 362 * \param size the maximum number of bytes we want to write |
| 363 * in the output stream. |
| 364 */ |
365 void CopyData(std::ostream *os, uint32_t size) const; | 365 void CopyData(std::ostream *os, uint32_t size) const; |
| 366 |
| 367 /** |
| 368 * \returns a COW copy of the packet. |
| 369 * |
| 370 * The returns packet will behave like an independent copy of |
| 371 * the original packet, even though they both share the |
| 372 * same datasets internally. |
| 373 */ |
| 374 Ptr<Packet> Copy (void) const; |
366 | 375 |
367 /** | 376 /** |
368 * A packet is allocated a new uid when it is created | 377 * A packet is allocated a new uid when it is created |
369 * empty or with zero-filled payload. | 378 * empty or with zero-filled payload. |
370 * | 379 * |
371 * Note: This uid is an internal uid and cannot be counted on to | 380 * Note: This uid is an internal uid and cannot be counted on to |
372 * provide an accurate counter of how many "simulated packets" of a | 381 * provide an accurate counter of how many "simulated packets" of a |
373 * particular protocol are in the system. It is not trivial to make | 382 * particular protocol are in the system. It is not trivial to make |
374 * this uid into such a counter, because of questions such as what | 383 * this uid into such a counter, because of questions such as what |
375 * should the uid be when the packet is sent over broadcast media, or | 384 * should the uid be when the packet is sent over broadcast media, or |
(...skipping 10 matching lines...) Expand all Loading... |
386 /** | 395 /** |
387 * \param os output stream in which the data should be printed. | 396 * \param os output stream in which the data should be printed. |
388 * | 397 * |
389 * Iterate over the headers and trailers present in this packet,· | 398 * Iterate over the headers and trailers present in this packet,· |
390 * from the first header to the last trailer and invoke, for | 399 * from the first header to the last trailer and invoke, for |
391 * each of them, the user-provided method Header::DoPrint or· | 400 * each of them, the user-provided method Header::DoPrint or· |
392 * Trailer::DoPrint methods. | 401 * Trailer::DoPrint methods. |
393 */ | 402 */ |
394 void Print (std::ostream &os) const; | 403 void Print (std::ostream &os) const; |
395 | 404 |
| 405 /** |
| 406 * \returns an iterator which points to the first 'item' |
| 407 * stored in this buffer. Note that this iterator will point |
| 408 * to an empty array of items if you don't call EnablePrinting |
| 409 * or EnableChecking before. |
| 410 * |
| 411 * \sa EnablePrinting EnableChecking |
| 412 */ |
396 PacketMetadata::ItemIterator BeginItem (void) const; | 413 PacketMetadata::ItemIterator BeginItem (void) const; |
397 | 414 |
398 /** | 415 /** |
399 * By default, packets do not keep around enough metadata to | 416 * By default, packets do not keep around enough metadata to |
400 * perform the operations requested by the Print methods. If you | 417 * perform the operations requested by the Print methods. If you |
401 * want to be able to invoke any of the two ::Print methods,· | 418 * want to be able to invoke any of the two ::Print methods,· |
402 * you need to invoke this method at least once during the· | 419 * you need to invoke this method at least once during the· |
403 * simulation setup and before any packet is created. | 420 * simulation setup and before any packet is created. |
404 */ | 421 */ |
405 static void EnablePrinting (void); | 422 static void EnablePrinting (void); |
(...skipping 19 matching lines...) Expand all Loading... |
425 | 442 |
426 /* | 443 /* |
427 * \param buffer a raw byte buffer to which the packet will be serialized | 444 * \param buffer a raw byte buffer to which the packet will be serialized |
428 * \param maxSize the max size of the buffer for bounds checking | 445 * \param maxSize the max size of the buffer for bounds checking |
429 * | 446 * |
430 * A packet is completely serialized and placed into the raw byte buffer | 447 * A packet is completely serialized and placed into the raw byte buffer |
431 * | 448 * |
432 * \returns zero if buffer size was too small | 449 * \returns zero if buffer size was too small |
433 */ | 450 */ |
434 uint32_t Serialize (uint8_t* buffer, uint32_t maxSize) const; | 451 uint32_t Serialize (uint8_t* buffer, uint32_t maxSize) const; |
435 | |
436 /* | |
437 * \param buffer a raw buffer which contains the contents for deserialization | |
438 * \param expectedSize the total number of bytes expected to be deserialized | |
439 * | |
440 * A packet is completely deserialized from the provided raw byte buffer | |
441 * | |
442 * \returns zero if the packet deserialization is incomplete | |
443 */ | |
444 uint32_t Deserialize (uint8_t* buffer, uint32_t expectedSize); | |
445 ·· | |
446 /** | |
447 * \returns a byte buffer | |
448 * | |
449 * This method creates a serialized representation of a Packet object | |
450 * ready to be transmitted over a network to another system. This | |
451 * serialized representation contains a copy of the packet byte buffer, | |
452 * the tag list, and the packet metadata (if there is one). | |
453 * | |
454 * This method will trigger calls to the Serialize and GetSerializedSize | |
455 * methods of each tag stored in this packet. | |
456 * | |
457 * This method will typically be used by parallel simulations where | |
458 * the simulated system is partitioned and each partition runs on | |
459 * a different CPU. | |
460 */ | |
461 Buffer Serialize (void) const; | |
462 /** | |
463 * \param buffer a byte buffer | |
464 * | |
465 * This method reads a byte buffer as created by Packet::Serialize | |
466 * and restores the state of the Packet to what it was prior to | |
467 * calling Serialize. | |
468 * | |
469 * This method will trigger calls to the Deserialize method | |
470 * of each tag stored in this packet. | |
471 * | |
472 * This method will typically be used by parallel simulations where | |
473 * the simulated system is partitioned and each partition runs on | |
474 * a different CPU. | |
475 */ | |
476 void Deserialize (Buffer buffer); | |
477 | 452 |
478 /** | 453 /** |
479 * \param tag the new tag to add to this packet | 454 * \param tag the new tag to add to this packet |
480 * | 455 * |
481 * Tag each byte included in this packet with the | 456 * Tag each byte included in this packet with the |
482 * new tag. | 457 * new tag. |
483 * | 458 * |
484 * Note that adding a tag is a const operation which is pretty· | 459 * Note that adding a tag is a const operation which is pretty· |
485 * un-intuitive. The rationale is that the content and behavior of | 460 * un-intuitive. The rationale is that the content and behavior of |
486 * a packet is _not_ changed when a tag is added to a packet: any | 461 * a packet is _not_ changed when a tag is added to a packet: any |
(...skipping 86 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
573 * how to associate something specific like nix-vector· | 548 * how to associate something specific like nix-vector· |
574 * with a packet. This design methodology· | 549 * with a packet. This design methodology· |
575 * should _not_ be followed, and is only here as an· | 550 * should _not_ be followed, and is only here as an· |
576 * impetus to fix this general issue. */ | 551 * impetus to fix this general issue. */ |
577 void SetNixVector (Ptr<NixVector>); | 552 void SetNixVector (Ptr<NixVector>); |
578 Ptr<NixVector> GetNixVector (void) const;· | 553 Ptr<NixVector> GetNixVector (void) const;· |
579 | 554 |
580 private: | 555 private: |
581 Packet (const Buffer &buffer, const ByteTagList &byteTagList,· | 556 Packet (const Buffer &buffer, const ByteTagList &byteTagList,· |
582 const PacketTagList &packetTagList, const PacketMetadata &metadata); | 557 const PacketTagList &packetTagList, const PacketMetadata &metadata); |
| 558 |
| 559 uint32_t Deserialize (uint8_t const*buffer, uint32_t size); |
| 560 ·· |
583 Buffer m_buffer; | 561 Buffer m_buffer; |
584 ByteTagList m_byteTagList; | 562 ByteTagList m_byteTagList; |
585 PacketTagList m_packetTagList; | 563 PacketTagList m_packetTagList; |
586 PacketMetadata m_metadata; | 564 PacketMetadata m_metadata; |
587 | 565 |
588 /* Please see comments above about nix-vector */ | 566 /* Please see comments above about nix-vector */ |
589 Ptr<NixVector> m_nixVector; | 567 Ptr<NixVector> m_nixVector; |
590 | 568 |
591 static uint32_t m_globalUid; | 569 static uint32_t m_globalUid; |
592 }; | 570 }; |
(...skipping 36 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
629 * Dirty operations will always be slower than non-dirty operations, | 607 * Dirty operations will always be slower than non-dirty operations, |
630 * sometimes by several orders of magnitude. However, even the | 608 * sometimes by several orders of magnitude. However, even the |
631 * dirty operations have been optimized for common use-cases which | 609 * dirty operations have been optimized for common use-cases which |
632 * means that most of the time, these operations will not trigger | 610 * means that most of the time, these operations will not trigger |
633 * data copies and will thus be still very fast. | 611 * data copies and will thus be still very fast. |
634 */ | 612 */ |
635 | 613 |
636 } // namespace ns3 | 614 } // namespace ns3 |
637 | 615 |
638 #endif /* PACKET_H */ | 616 #endif /* PACKET_H */ |
LEFT | RIGHT |