A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::PacketTagList Class Reference

List of the packet tags stored in a packet. More...

#include "packet-tag-list.h"

+ Collaboration diagram for ns3::PacketTagList:

Classes

struct  TagData
 Tree node for sharing serialized tags. More...
 

Public Member Functions

 PacketTagList ()
 Create a new PacketTagList.
 
 PacketTagList (const PacketTagList &o)
 Copy constructor.
 
 ~PacketTagList ()
 Destructor.
 
void Add (const Tag &tag) const
 Add a tag to the head of this branch.
 
uint32_t Deserialize (const uint32_t *buffer, uint32_t size)
 Deserialize tag list from the provided buffer.
 
uint32_t GetSerializedSize () const
 Returns number of bytes required for packet serialization.
 
const PacketTagList::TagDataHead () const
 
PacketTagListoperator= (const PacketTagList &o)
 Assignment.
 
bool Peek (Tag &tag) const
 Find a tag and return its value.
 
bool Remove (Tag &tag)
 Remove (the first instance of) tag from the list.
 
void RemoveAll ()
 Remove all tags from this list (up to the first merge).
 
bool Replace (Tag &tag)
 Replace the value of a tag.
 
uint32_t Serialize (uint32_t *buffer, uint32_t maxSize) const
 Serialize the tag list into a byte buffer.
 

Private Types

typedef bool(PacketTagList::* COWWriter) (Tag &tag, bool preMerge, TagData *cur, TagData **prevNext)
 Typedef of method function pointer for copy-on-write operations.
 

Private Member Functions

bool COWTraverse (Tag &tag, PacketTagList::COWWriter Writer)
 Traverse the list implementing copy-on-write, using Writer.
 
bool RemoveWriter (Tag &tag, bool preMerge, TagData *cur, TagData **prevNext)
 Copy-on-write implementing Remove.
 
bool ReplaceWriter (Tag &tag, bool preMerge, TagData *cur, TagData **prevNext)
 Copy-on-write implementing Replace.
 

Static Private Member Functions

static TagDataCreateTagData (size_t dataSize)
 Allocate and construct a TagData struct, sizing the data area large enough to serialize dataSize bytes from a Tag.
 

Private Attributes

TagDatam_next
 Pointer to first TagData on the list.
 

Detailed Description

List of the packet tags stored in a packet.

This class is mostly private to the Packet implementation and users should never have to access it directly.

Internal:

The implementation of this class is a bit tricky. Refer to this diagram in the discussion that follows.

  • Tags are stored in serialized form in a tree of TagData structures. (T1-T7 in the diagram)
  • Each TagData points (next pointers in the diagram) toward the root of the tree, which is a null pointer.
  • count is the number of incoming pointers to this TagData. Branch points, where branches merge or join, have count > 1 (T3, T5); successive links along a branch have count = 1 (T1, T2, T4, T6, T7).
  • Each PacketTagList points to a specific TagData, which is the most recent Tag added to the packet. (T5-T7)
  • Conceptually, therefore, each Packet has a PacketTagList which points to a singly-linked list of TagData.
Copy-on-write is implemented as follows:
  • Add prepends the new tag to the list (growing that branch of the tree, as T6). This is a constant time operation, and does not affect any other PacketTagList's, hence this is a const function.
  • Copy constructor (PacketTagList(const PacketTagList & o)) and assignment (operator=(const PacketTagList & o)) simply join the tree at the same place as the original PacketTagList o, incrementing the count. For assignment, the old branch is deleted, up to the first branch point, which has its count decremented. (PacketTagList B started as a copy of PacketTagList A, before T6 was added to B).
  • Remove and Replace are a little tricky, depending on where the target tag is found relative to the first branch point:
    • Target before the first branch point:
      The target is just dealt with in place (linked around and deleted, in the case of Remove; rewritten in the case of Replace).
    • Target at or after the first branch point:
      The portion of the list between the first branch and the target is shared. This portion is copied before the Remove or Replace is performed.

Definition at line 124 of file packet-tag-list.h.

Member Typedef Documentation

◆ COWWriter

typedef bool(PacketTagList::* ns3::PacketTagList::COWWriter) (Tag &tag, bool preMerge, TagData *cur, TagData **prevNext)
private

Typedef of method function pointer for copy-on-write operations.

Parameters
[in]tagThe tag type to operate on.
[in]preMergeTrue if tag was found before the first merge, false otherwise.
[in]curPointer to the tag.
[in]prevNextPointer to the struct TagData.next pointer pointing to cur.
Returns
True if operation successful, false otherwise

Definition at line 267 of file packet-tag-list.h.

Constructor & Destructor Documentation

◆ PacketTagList() [1/2]

ns3::PacketTagList::PacketTagList ( )
inline

Create a new PacketTagList.

Definition at line 319 of file packet-tag-list.h.

◆ PacketTagList() [2/2]

ns3::PacketTagList::PacketTagList ( const PacketTagList o)
inline

Copy constructor.

Parameters
[in]oThe PacketTagList to copy.

This makes a light-weight copy by RemoveAll, then pointing to the same TagData as o.

Definition at line 324 of file packet-tag-list.h.

References ns3::PacketTagList::TagData::count, and m_next.

◆ ~PacketTagList()

ns3::PacketTagList::~PacketTagList ( )
inline

Destructor.

RemoveAll's the tags up to the first merge.

Definition at line 350 of file packet-tag-list.h.

References RemoveAll().

+ Here is the call graph for this function:

Member Function Documentation

◆ Add()

void ns3::PacketTagList::Add ( const Tag tag) const

Add a tag to the head of this branch.

Parameters
[in]tagThe tag to add

Definition at line 262 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, CreateTagData(), ns3::PacketTagList::TagData::data, ns3::ObjectBase::GetInstanceTypeId(), ns3::TypeId::GetName(), ns3::Tag::GetSerializedSize(), m_next, ns3::PacketTagList::TagData::next, NS_ASSERT_MSG, NS_LOG_FUNCTION, ns3::Tag::Serialize(), ns3::PacketTagList::TagData::size, and ns3::PacketTagList::TagData::tid.

Referenced by ns3::Packet::AddPacketTag(), PacketTagListTest::AddRemoveTime(), PacketTagListTest::DoRun(), and Replace().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ COWTraverse()

bool ns3::PacketTagList::COWTraverse ( Tag tag,
PacketTagList::COWWriter  Writer 
)
private

Traverse the list implementing copy-on-write, using Writer.

Parameters
[in]tagThe tag type to operate on.
[in]WriterThe copy-on-write function to use.
Returns
True if tag found, false otherwise.

Definition at line 56 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, CreateTagData(), ns3::PacketTagList::TagData::data, ns3::ObjectBase::GetInstanceTypeId(), m_next, ns3::PacketTagList::TagData::next, NS_ASSERT, NS_LOG_FUNCTION, NS_LOG_INFO, ns3::PacketTagList::TagData::size, and ns3::PacketTagList::TagData::tid.

Referenced by Remove(), and Replace().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ CreateTagData()

PacketTagList::TagData * ns3::PacketTagList::CreateTagData ( size_t  dataSize)
staticprivate

Allocate and construct a TagData struct, sizing the data area large enough to serialize dataSize bytes from a Tag.

Parameters
[in]dataSizeThe serialized size of the Tag.
Returns
The newly constructed TagData object.

Definition at line 41 of file packet-tag-list.cc.

References NS_ASSERT_MSG, and ns3::PacketTagList::TagData::size.

Referenced by Add(), COWTraverse(), Deserialize(), and ReplaceWriter().

+ Here is the caller graph for this function:

◆ Deserialize()

uint32_t ns3::PacketTagList::Deserialize ( const uint32_t buffer,
uint32_t  size 
)

Deserialize tag list from the provided buffer.

Parameters
[in]bufferThe buffer to read from.
[in]sizeThe number of bytes to deserialize.
Returns
zero if complete tag list is not deserialized

Definition at line 395 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, CreateTagData(), ns3::PacketTagList::TagData::data, ns3::TypeId::LookupByHash(), m_next, ns3::PacketTagList::TagData::next, NS_ASSERT, NS_LOG_FUNCTION, NS_LOG_INFO, and ns3::PacketTagList::TagData::tid.

Referenced by ns3::Packet::Deserialize().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetSerializedSize()

uint32_t ns3::PacketTagList::GetSerializedSize ( ) const

Returns number of bytes required for packet serialization.

Returns
number of bytes required for packet serialization

Definition at line 307 of file packet-tag-list.cc.

References m_next, ns3::PacketTagList::TagData::next, and NS_LOG_FUNCTION_NOARGS.

Referenced by ns3::Packet::GetSerializedSize(), and ns3::Packet::Serialize().

+ Here is the caller graph for this function:

◆ Head()

const PacketTagList::TagData * ns3::PacketTagList::Head ( ) const
Returns
pointer to head of tag list

Definition at line 301 of file packet-tag-list.cc.

References m_next.

Referenced by ns3::Packet::GetPacketTagIterator().

+ Here is the caller graph for this function:

◆ operator=()

PacketTagList & ns3::PacketTagList::operator= ( const PacketTagList o)
inline

Assignment.

Parameters
[in]oThe PacketTagList to copy.
Returns
the copied object

This makes a light-weight copy by RemoveAll, then pointing to the same TagData as o.

Definition at line 334 of file packet-tag-list.h.

References ns3::PacketTagList::TagData::count, m_next, and RemoveAll().

+ Here is the call graph for this function:

◆ Peek()

bool ns3::PacketTagList::Peek ( Tag tag) const

Find a tag and return its value.

Parameters
[in,out]tagThe tag type to find. If found, tag is set to the value of the tag found.
Returns
True if tag is found, false otherwise.

Definition at line 283 of file packet-tag-list.cc.

References ns3::Tag::Deserialize(), ns3::ObjectBase::GetInstanceTypeId(), m_next, ns3::PacketTagList::TagData::next, and NS_LOG_FUNCTION.

Referenced by PacketTagListTest::CheckRef(), PacketTagListTest::DoRun(), and ns3::Packet::PeekPacketTag().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Remove()

bool ns3::PacketTagList::Remove ( Tag tag)

Remove (the first instance of) tag from the list.

Parameters
[in,out]tagThe tag type to remove. If found, tag is set to the value of the tag found.
Returns
True if tag is found, false otherwise.

Definition at line 176 of file packet-tag-list.cc.

References COWTraverse(), and RemoveWriter().

Referenced by PacketTagListTest::AddRemoveTime(), PacketTagListTest::DoRun(), and ns3::Packet::RemovePacketTag().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ RemoveAll()

void ns3::PacketTagList::RemoveAll ( )
inline

Remove all tags from this list (up to the first merge).

Definition at line 356 of file packet-tag-list.h.

References m_next, ns3::PacketTagList::TagData::next, and prev.

Referenced by ~PacketTagList(), operator=(), and ns3::Packet::RemoveAllPacketTags().

+ Here is the caller graph for this function:

◆ RemoveWriter()

bool ns3::PacketTagList::RemoveWriter ( Tag tag,
bool  preMerge,
PacketTagList::TagData cur,
PacketTagList::TagData **  prevNext 
)
private

Copy-on-write implementing Remove.

Parameters
[in]tagThe target tag type to remove.
[in]preMergeTrue if tag was found before the first merge, false otherwise.
[in]curPointer to the tag.
[in]prevNextPointer to the struct TagData.next pointer pointing to cur.
Returns
True, since tag will definitely be removed.

Definition at line 183 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, ns3::PacketTagList::TagData::data, ns3::Tag::Deserialize(), ns3::PacketTagList::TagData::next, NS_LOG_FUNCTION_NOARGS, and ns3::PacketTagList::TagData::size.

Referenced by Remove().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Replace()

bool ns3::PacketTagList::Replace ( Tag tag)

Replace the value of a tag.

Parameters
[in]tagThe tag type to replace. To get the old value of the tag, use Peek first.
Returns
True if tag is found, false otherwise. If tag wasn't found, Add is performed instead (so the list is guaranteed to have the new tag value either way).

Definition at line 216 of file packet-tag-list.cc.

References Add(), COWTraverse(), and ReplaceWriter().

Referenced by ns3::Packet::ReplacePacketTag().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ ReplaceWriter()

bool ns3::PacketTagList::ReplaceWriter ( Tag tag,
bool  preMerge,
PacketTagList::TagData cur,
PacketTagList::TagData **  prevNext 
)
private

Copy-on-write implementing Replace.

Parameters
[in]tagThe target tag type to replace
[in]preMergeTrue if tag was found before the first merge, false otherwise.
[in]curPointer to the tag
[in]prevNextPointer to the struct TagData.next pointer pointing to cur.
Returns
True, since tag value will definitely be replaced.

Definition at line 228 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, CreateTagData(), ns3::PacketTagList::TagData::data, ns3::ObjectBase::GetInstanceTypeId(), ns3::Tag::GetSerializedSize(), ns3::PacketTagList::TagData::next, NS_LOG_FUNCTION_NOARGS, ns3::Tag::Serialize(), ns3::PacketTagList::TagData::size, and ns3::PacketTagList::TagData::tid.

Referenced by Replace().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Serialize()

uint32_t ns3::PacketTagList::Serialize ( uint32_t buffer,
uint32_t  maxSize 
) const

Serialize the tag list into a byte buffer.

Parameters
[in,out]bufferThe byte buffer to which the tag list will be serialized
[in]maxSizeMax The max size of the buffer for bounds checking
Returns
zero if complete tag list is not serialized

Definition at line 332 of file packet-tag-list.cc.

References m_next, ns3::PacketTagList::TagData::next, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by ns3::Packet::Serialize().

+ Here is the caller graph for this function:

Member Data Documentation

◆ m_next

TagData* ns3::PacketTagList::m_next
private

Pointer to first TagData on the list.

Definition at line 307 of file packet-tag-list.h.

Referenced by PacketTagList(), Add(), COWTraverse(), Deserialize(), GetSerializedSize(), Head(), operator=(), Peek(), RemoveAll(), and Serialize().


The documentation for this class was generated from the following files: