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::TagData *	Head () const
PacketTagList &	operator= (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 TagData *	CreateTagData (size_t dataSize)
	Allocate and construct a TagData struct, sizing the data area large enough to serialize dataSize bytes from a Tag.

Private Attributes
TagData *	m_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 113 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]	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 256 of file packet-tag-list.h.

Constructor & Destructor Documentation

◆ PacketTagList() [1/2]

ns3::PacketTagList::PacketTagList ( )

inline

Create a new PacketTagList.

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

References m_next.

Referenced by PacketTagList(), Add(), and operator=().

Here is the caller graph for this function:

◆ PacketTagList() [2/2]

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

References PacketTagList(), and m_next.

Here is the call graph for this function:

◆ ~PacketTagList()

ns3::PacketTagList::~PacketTagList ( )

inline

Destructor.

RemoveAll's the tags up to the first merge.

Definition at line 339 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] tag The tag to add

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

References PacketTagList(), 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 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]	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 45 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] dataSize The serialized size of the Tag.

Returns: The newly constructed TagData object.

Definition at line 30 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]	buffer	The buffer to read from.
[in]	size	The number of bytes to deserialize.

Returns: zero if complete tag list is not deserialized

Definition at line 384 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.

Here is the call 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 296 of file packet-tag-list.cc.

References m_next, and NS_LOG_FUNCTION_NOARGS.

◆ Head()

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

Returns: pointer to head of tag list

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

References m_next.

◆ operator=()

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

References PacketTagList(), 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] 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 272 of file packet-tag-list.cc.

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

Referenced by PacketTagListTest::CheckRef(), and PacketTagListTest::DoRun().

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

References COWTraverse(), and RemoveWriter().

Referenced by PacketTagListTest::AddRemoveTime(), and PacketTagListTest::DoRun().

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

References m_next, and prev.

Referenced by ~PacketTagList(), and operator=().

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]	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 172 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] 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 205 of file packet-tag-list.cc.

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

Here is the call 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]	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 217 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]	buffer	The byte buffer to which the tag list will be serialized
[in]	maxSize	Max The max size of the buffer for bounds checking

Returns: zero if complete tag list is not serialized

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

References m_next, NS_LOG_FUNCTION, and NS_LOG_INFO.

Member Data Documentation

◆ m_next

TagData* ns3::PacketTagList::m_next

private

Pointer to first TagData on the list.

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

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

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

◆ Deserialize()

◆ GetSerializedSize()

◆ Head()

◆ operator=()

◆ Peek()

◆ Remove()

◆ RemoveAll()

◆ RemoveWriter()

◆ Replace()

◆ ReplaceWriter()

◆ Serialize()

Member Data Documentation

◆ m_next