From 4fa19c35b583bc47d2f21a995d7df3c20320fd22 Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Wed, 6 Sep 2006 16:46:26 +0200 Subject: [PATCH] improve documentation and remove updateTag method --- src/common/chunk.h | 6 ++- src/common/packet.h | 121 +++++++++++++++++++++++++++++++++++++++++--- src/common/tags.cc | 16 ------ src/common/tags.h | 14 ----- 4 files changed, 118 insertions(+), 39 deletions(-) diff --git a/src/common/chunk.h b/src/common/chunk.h index f84c5c63e..91bdb2d36 100644 --- a/src/common/chunk.h +++ b/src/common/chunk.h @@ -33,7 +33,11 @@ namespace ns3 { * * Every Protocol header which needs to be inserted and removed * from a Packet instance must derive from this abstract base class - * and implement the private pure virtual methods defined here. + * and implement the private pure virtual methods listed below: + * - ns3::Chunk::addTo + * - ns3::Chunk::removeFrom + * - ns3::Chunk::peekFrom + * - ns3::Chunk::print */ class Chunk { public: diff --git a/src/common/packet.h b/src/common/packet.h index 0ae1dcf9f..f0f469863 100644 --- a/src/common/packet.h +++ b/src/common/packet.h @@ -29,29 +29,140 @@ namespace ns3 { +/** + * \brief network packets + */ class Packet { public: typedef Callback PacketReadWriteCallback; + /** + * Create an empty packet. + */ Packet (); + /** + * Create a packet with a zero-filled payload. + * The memory necessary for the payload is not allocated: + * it will be allocated at any later point if you attempt + * to fragment this packet or to access the zero-filled + * bytes. + * + * \param size the size of the zero-filled payload + */ Packet (uint32_t size); + /** + * Create a new packet which contains a fragment of the original + * packet. + * + * \param start offset from start of packet to start of fragment to create + * \param length length of fragment to create + * \returns a fragment of the original packet + */ Packet createFragment (uint32_t start, uint32_t length) const; + /** + * \returns the size in bytes of the packet (including the zero-filled + * initial payload) + */ uint32_t getSize (void) const; + /** + * Add chunk to this packet. This method invokes the + * ns3::Chunk::addTo method to request the chunk to serialize + * itself in the packet buffer. + * + * \param chunk a pointer to the chunk to add to this packet. + */ void add (Chunk *chunk); + /** + * Deserialize chunk from this packet. This method invokes the + * ns3::Chunk::peekFrom method to request the chunk to deserialize + * itself from the packet buffer. This method does not remove + * the chunk from the buffer. + * + * \param chunk a pointer to the chunk to deserialize from the buffer + */ void peek (Chunk *chunk) const; + /** + * Remove a deserialized chunk from the internal buffer. + * This method invokes ns3::Chunk::removeFrom to complete + * the work initiated by Packet::peek and ns3::Chunk::peekFrom. + * + * \param chunk a pointer to the chunk to remove from the internal buffer. + */ void remove (Chunk *chunk); + /** + * Attach a tag to this packet. The tag is fully copied + * in a packet-specific internal buffer. This operation + * is expected to be really fast. + * + * \param tag a pointer to the tag to attach to this packet. + */ template void addTag (T const *tag); + /** + * Remove a tag from this packet. The data stored internally + * for this tag is copied in the input tag if an instance + * of this tag type is present in the internal buffer. If this + * tag type is not present, the input tag is not modified. + * + * This operation can be potentially slow and might trigger + * unexpectedly large memory allocations. It is thus + * usually a better idea to create a copy of this packet, + * and invoke removeAllTags on the copy to remove all + * tags rather than remove the tags one by one from a packet. + * + * \param tag a pointer to the tag to remove from this packet + * \returns true if an instance of this tag type is stored + * in this packet, false otherwise. + */ template bool removeTag (T *tag); + /** + * Copy a tag stored internally to the input tag. If no instance + * of this tag is present internally, the input tag is not modified. + * + * \param tag a pointer to the tag to read from this packet + * \returns true if an instance of this tag type is stored + * in this packet, false otherwise. + */ template bool peekTag (T *tag) const; - template - bool updateTag (T const*tag); + /** + * Remove all the tags stored in this packet. This operation is + * much much faster than invoking removeTag n times. + */ void removeAllTags (void); void write (PacketReadWriteCallback callback) const; + /** + * Concatenate the input packet at the end of the current + * packet. + * + * \param packet packet to concatenate + */ void addAtEnd (Packet packet); + /** + * Concatenate the fragment of the input packet identified + * by the offset and size parameters at the end of the current + * packet. + * + * \param packet to concatenate + * \param offset offset of fragment to copy from the start of the input packet + * \param size size of fragment of input packet to copy. + */ void addAtEnd (Packet packet, uint32_t offset, uint32_t size); + /** + * Remove size bytes from the end of the current packet + * It is safe to remove more bytes that what is present in + * the packet. + * + * \param size number of bytes from remove + */ void removeAtEnd (uint32_t size); + /** + * Remove size bytes from the start of the current packet. + * It is safe to remove more bytes that what is present in + * the packet. + * + * \param size number of bytes from remove + */ void removeAtStart (uint32_t size); private: @@ -85,12 +196,6 @@ bool Packet::peekTag (T *tag) const { return m_tags.peek (tag); } -template -bool Packet::updateTag (T const*tag) -{ - return m_tags.update (tag); -} - }; // namespace ns3 #endif /* PACKET_H */ diff --git a/src/common/tags.cc b/src/common/tags.cc index 0beb2d1a5..569a8084f 100644 --- a/src/common/tags.cc +++ b/src/common/tags.cc @@ -149,22 +149,6 @@ Tags::remove (uint32_t id) return true; } -bool -Tags::update (uint8_t const*buffer, uint32_t id) -{ - if (!remove (id)) { - return false; - } - struct TagData *newStart = allocData (); - newStart->m_count = 1; - newStart->m_next = 0; - newStart->m_id = id; - memcpy (newStart->m_data, buffer, Tags::SIZE); - newStart->m_next = m_next; - m_next = newStart; - return true; -} - void Tags::prettyPrint (std::ostream &os) { diff --git a/src/common/tags.h b/src/common/tags.h index 6f9db0b8b..ae9e14e5d 100644 --- a/src/common/tags.h +++ b/src/common/tags.h @@ -46,9 +46,6 @@ public: template bool peek (T *tag) const; - template - bool update (T const*tag); - void prettyPrint (std::ostream &os); inline void removeAll (void); @@ -69,7 +66,6 @@ private: }; bool remove (uint32_t id); - bool update (uint8_t const*buffer, uint32_t id); struct Tags::TagData *allocData (void); void freeData (struct TagData *data); @@ -235,16 +231,6 @@ Tags::peek (T *tag) const return false; } -template -bool -Tags::update (T const*tag) -{ - assert (sizeof (T) <= Tags::SIZE); - uint8_t const*buf = reinterpret_cast (tag); - return update (buf, TypeUid::getUid ()); -} - - Tags::Tags () : m_next () {}