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

PacketTagList &	operator= (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 TagData *	m_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.

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]	tag	The tag type to operate on.
[in]	preMerge	True if tag was found before the first merge, false otherwise.
[in]	cur	Pointer to the tag.
[in]	prevNext	Pointer to the struct TagData.next pointer pointing to cur.

Returns: True if operation successful, false otherwise

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

Constructor & Destructor Documentation

ns3::PacketTagList::PacketTagList ( )

inline

Create a new PacketTagList.

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

ns3::PacketTagList::PacketTagList ( PacketTagList const & o )

inline

Copy constructor.

Parameters

[in] o The PacketTagList to copy.

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

Definition at line 308 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 334 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

Add a tag to the head of this branch.

Parameters

[in] tag The tag to add

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

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

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

private

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

Parameters

[in]	tag	The tag type to operate on.
[in]	Writer	The copy-on-write function to use.

Returns: True if tag found, false otherwise.

Definition at line 39 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 283 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] o The PacketTagList to copy.

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

Definition at line 318 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] tag The 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 265 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] tag The 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 159 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 340 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]	tag	The target tag type to remove.
[in]	preMerge	True if tag was found before the first merge, false otherwise.
[in]	cur	Pointer to the tag.
[in]	prevNext	Pointer to the struct TagData.next pointer pointing to cur.

Returns: True, since tag will definitely be removed.

Definition at line 166 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] tag The 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 198 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]	tag	The target tag type to replace
[in]	preMerge	True if tag was found before the first merge, false otherwise.
[in]	cur	Pointer to the tag
[in]	prevNext	Pointer to the struct TagData.next pointer pointing to cur.