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

#include "packet-tag-list.h"

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...

Static Private Member Functions
static TagData *	CreateTagData (size_t dataSize)
	Allocate and construct a TagData struct, sizing the data area large enough to serialize dataSize bytes from a Tag. 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.

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

Member Typedef Documentation

◆ COWWriter

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 244 of file packet-tag-list.h.

Constructor & Destructor Documentation

◆ PacketTagList() [1/2]

ns3::PacketTagList::PacketTagList ( )

inline

Create a new PacketTagList.

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

◆ PacketTagList() [2/2]

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 300 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 326 of file packet-tag-list.h.

References RemoveAll().

Member Function Documentation

◆ Add()

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

References ns3::PacketTagList::TagData::count, CreateTagData(), ns3::PacketTagList::TagData::data, ns3::ObjectBase::GetInstanceTypeId(), 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().

◆ COWTraverse()

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 55 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().

◆ 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] dataSize The serialized size of the Tag.

Returns: The newly constructed TagData object.

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

References max, NS_ASSERT_MSG(), and ns3::PacketTagList::TagData::size.

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

◆ Head()

const struct PacketTagList::TagData * ns3::PacketTagList::Head ( void ) const

Returns: pointer to head of tag list

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

References m_next.

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

◆ operator=()

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

inline

Assignment.

Parameters

[in] o The 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 310 of file packet-tag-list.h.

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

◆ Peek()

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 280 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().

◆ Remove()

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

References COWTraverse(), and RemoveWriter().

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

◆ RemoveAll()

void ns3::PacketTagList::RemoveAll ( void )

inline

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

Definition at line 332 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().

◆ RemoveWriter()

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 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().

◆ Replace()

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

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

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

◆ ReplaceWriter()

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.

Returns: True, since tag value will definitely be replaced.

Definition at line 227 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().

Member Data Documentation

◆ m_next

struct TagData* ns3::PacketTagList::m_next

private

Pointer to first TagData on the list.

Definition at line 284 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:

src/network/model/packet-tag-list.h
src/network/model/packet-tag-list.cc

Classes

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ COWWriter

Constructor & Destructor Documentation

◆ PacketTagList() [1/2]

◆ PacketTagList() [2/2]

◆ ~PacketTagList()

Member Function Documentation

◆ Add()

◆ COWTraverse()

◆ CreateTagData()

◆ Head()

◆ operator=()

◆ Peek()

◆ Remove()

◆ RemoveAll()

◆ RemoveWriter()

◆ Replace()

◆ ReplaceWriter()

Member Data Documentation

◆ m_next