A Discrete-Event Network Simulator
API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
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. More...
 
 PacketTagList (PacketTagList const &o)
 Copy constructor. More...
 
 ~PacketTagList ()
 Destructor. More...
 
void Add (Tag const &tag) const
 Add a tag to the head of this branch. More...
 
const struct
PacketTagList::TagData
Head (void) const
 
PacketTagListoperator= (PacketTagList const &o)
 Assignment. More...
 
bool Peek (Tag &tag) const
 Find a tag and return its value. More...
 
bool Remove (Tag &tag)
 Remove (the first instance of) tag from the list. More...
 
void RemoveAll (void)
 Remove all tags from this list (up to the first merge). More...
 
bool Replace (Tag &tag)
 Replace the value of a tag. More...
 

Private Types

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

Private Member Functions

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

Private Attributes

struct TagDatam_next
 Pointer to first TagData on the list. More...
 

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.

dot_inline_dotgraph_1.png
  • 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.
Memory Management:

Packet tags must serialize to a finite maximum size, see TagData

This documentation entitles the original author to a free beer.

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

Member Typedef Documentation

typedef bool(PacketTagList::* ns3::PacketTagList::COWWriter)(Tag &tag, bool preMerge, struct TagData *cur, struct 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 254 of file packet-tag-list.h.

Constructor & Destructor Documentation

ns3::PacketTagList::PacketTagList ( )
inline

Create a new PacketTagList.

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

ns3::PacketTagList::PacketTagList ( PacketTagList const &  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 309 of file packet-tag-list.h.

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

ns3::PacketTagList::~PacketTagList ( )
inline

Destructor.

RemoveAll's the tags up to the first merge.

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

References RemoveAll().

+ Here is the call graph for this function:

Member Function Documentation

void ns3::PacketTagList::Add ( Tag const &  tag) const
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 38 of file packet-tag-list.cc.

References ns3::PacketTagList::TagData::count, ns3::PacketTagList::TagData::data, ns3::ObjectBase::GetInstanceTypeId(), m_next, ns3::PacketTagList::TagData::MAX_SIZE, ns3::PacketTagList::TagData::next, NS_ASSERT, NS_LOG_FUNCTION, NS_LOG_INFO, 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:

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

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

References m_next.

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

+ Here is the caller graph for this function:

PacketTagList & ns3::PacketTagList::operator= ( PacketTagList const &  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 319 of file packet-tag-list.h.

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

+ Here is the call graph for this function:

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 264 of file packet-tag-list.cc.

References ns3::Tag::Deserialize(), ns3::ObjectBase::GetInstanceTypeId(), m_next, ns3::PacketTagList::TagData::MAX_SIZE, 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:

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 158 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:

void ns3::PacketTagList::RemoveAll ( void  )
inline

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

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

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

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

+ Here is the caller graph for this function:

bool ns3::PacketTagList::RemoveWriter ( Tag tag,
bool  preMerge,
struct TagData cur,
struct 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 165 of file packet-tag-list.cc.

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

Referenced by Remove().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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 197 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:

bool ns3::PacketTagList::ReplaceWriter ( Tag tag,
bool  preMerge,
struct TagData cur,
struct 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 209 of file packet-tag-list.cc.

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

Referenced by Replace().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

Member Data Documentation

struct TagData* ns3::PacketTagList::m_next
private

Pointer to first TagData on the list.

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

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


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