automatically resized byte buffer More...

#include <buffer.h>

Collaboration diagram for ns3::Buffer:

Classes
struct	Data
class	Iterator
	iterator in a Buffer instance More...

Public Member Functions
	Buffer (Buffer const &o)
	Buffer ()
	Buffer (uint32_t dataSize)
	Buffer (uint32_t dataSize, bool initialize)
	~Buffer ()
bool	AddAtEnd (uint32_t end)
void	AddAtEnd (const Buffer &o)
bool	AddAtStart (uint32_t start)
Buffer::Iterator	Begin (void) const
void	CopyData (std::ostream *os, uint32_t size) const
uint32_t	CopyData (uint8_t *buffer, uint32_t size) const
Buffer	CreateFragment (uint32_t start, uint32_t length) const
Buffer	CreateFullCopy (void) const
uint32_t	Deserialize (const uint8_t *buffer, uint32_t size)
Buffer::Iterator	End (void) const
int32_t	GetCurrentEndOffset (void) const
int32_t	GetCurrentStartOffset (void) const
uint32_t	GetSerializedSize (void) const
uint32_t	GetSize (void) const
Buffer &	operator= (Buffer const &o)
uint8_t const *	PeekData (void) const
void	RemoveAtEnd (uint32_t end)
void	RemoveAtStart (uint32_t start)
uint32_t	Serialize (uint8_t *buffer, uint32_t maxSize) const

Private Member Functions
bool	CheckInternalState (void) const
uint32_t	GetInternalEnd (void) const
uint32_t	GetInternalSize (void) const
void	Initialize (uint32_t zeroSize)
void	TransformIntoRealBuffer (void) const

Static Private Member Functions
static struct Buffer::Data *	Allocate (uint32_t reqSize)
static struct Buffer::Data *	Create (uint32_t size)
static void	Deallocate (struct Buffer::Data *data)
static void	Recycle (struct Buffer::Data *data)

Private Attributes
struct Data *	m_data
uint32_t	m_end
uint32_t	m_maxZeroAreaStart
uint32_t	m_start
uint32_t	m_zeroAreaEnd
uint32_t	m_zeroAreaStart

Static Private Attributes
static uint32_t	g_recommendedStart = 0

Detailed Description

automatically resized byte buffer

This represents a buffer of bytes. Its size is automatically adjusted to hold any data prepended or appended by the user. Its implementation is optimized to ensure that the number of buffer resizes is minimized, by creating new Buffers of the maximum size ever used. The correct maximum size is learned at runtime during use by recording the maximum size of each packet.

The implementation of the Buffer class uses a COW (Copy On Write) technique to ensure that the underlying data buffer which holds the data bytes is shared among a lot of Buffer instances despite data being added or removed from them.

When multiple Buffer instances hold a reference to the same underlying BufferData object, they must be able to detect when the operation they want to perform should trigger a copy of the BufferData. If the BufferData::m_count field is one, it means that there exist only one instance of Buffer which references the BufferData instance so, it is safe to modify it. It is also safe to modify the content of a BufferData if the modification falls outside of the "dirty area" defined by the BufferData. In every other case, the BufferData must be copied before being modified.

To understand the way the Buffer::Add and Buffer::Remove methods work, you first need to understand the "virtual offsets" used to keep track of the content of buffers. Each Buffer instance contains real data bytes in its BufferData instance but it also contains "virtual zero data" which typically is used to represent application-level payload. No memory is allocated to store the zero bytes of application-level payload unless the user fragments a Buffer: this application-level payload is kept track of with a pair of integers which describe where in the buffer content the "virtual zero area" starts and ends.

* ***: unused bytes
* xxx: bytes "added" at the front of the zero area
* ...: bytes "added" at the back of the zero area
* 000: virtual zero bytes
*
* Real byte buffer:      |********xxxxxxxxxxxx.........*****|
*                        |--------^ m_start
*                        |-------------------^ m_zeroAreaStart
*                        |-----------------------------^ m_end - (m_zeroAreaEnd - m_zeroAreaStart)
* virtual byte buffer:           |xxxxxxxxxxxx0000000000000.........|
*                        |--------^ m_start
*                        |--------------------^ m_zeroAreaStart
*                        |---------------------------------^ m_zeroAreaEnd
*                        |------------------------------------------^ m_end
*

A simple state invariant is that m_start <= m_zeroStart <= m_zeroEnd <= m_end

Definition at line 92 of file buffer.h.

Constructor & Destructor Documentation

ns3::Buffer::Buffer ( Buffer const & o )

inline

Definition at line 856 of file buffer.h.

References CheckInternalState(), ns3::Buffer::Data::m_count, m_data, and NS_ASSERT.

Here is the call graph for this function:

ns3::Buffer::Buffer ( )

Definition at line 177 of file buffer.cc.

References Initialize(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

ns3::Buffer::Buffer ( uint32_t dataSize )

Definition at line 183 of file buffer.cc.

References Initialize(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

ns3::Buffer::Buffer	(	uint32_t	dataSize,
		bool	initialize
	)

Definition at line 189 of file buffer.cc.

References Initialize(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

ns3::Buffer::~Buffer ( )

Definition at line 272 of file buffer.cc.

References CheckInternalState(), g_recommendedStart, ns3::Buffer::Data::m_count, m_data, m_maxZeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, and Recycle().

Here is the call graph for this function:

Member Function Documentation

bool ns3::Buffer::AddAtEnd ( uint32_t end )

Parameters

end	size to reserve

Returns: true if the buffer needed resizing, false otherwise.

Add bytes at the end of the Buffer. The content of these bytes is undefined but debugging builds initialize them to 0x33. Any call to this method invalidates any Iterator pointing to this Buffer.

Definition at line 347 of file buffer.cc.

References CheckInternalState(), Create(), GetInternalEnd(), GetInternalSize(), LOG_INTERNAL_STATE, ns3::Buffer::Data::m_count, ns3::Buffer::Data::m_data, m_data, ns3::Buffer::Data::m_dirtyEnd, ns3::Buffer::Data::m_dirtyStart, m_end, m_maxZeroAreaStart, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, and Recycle().

Referenced by ns3::Packet::AddAtEnd(), AddAtEnd(), ns3::dsr::DsrOptionField::AddDsrOption(), ns3::OptionField::AddOption(), ns3::Packet::AddPaddingAtEnd(), ns3::Packet::AddTrailer(), CreateFullCopy(), ns3::Ipv6ExtensionHeader::Deserialize(), ns3::dsr::DsrOptionHeader::Deserialize(), ns3::Ipv6OptionHeader::Deserialize(), ns3::dsr::DsrFsHeader::Deserialize(), ns3::OptionField::Deserialize(), ns3::dsr::DsrOptionField::Deserialize(), Deserialize(), ns3::dsr::DsrOptionRerrHeader::Deserialize(), ns3::BufferTest::DoRun(), and ns3::WifiInformationElement::operator==().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::Buffer::AddAtEnd ( const Buffer & o )

Parameters

o	the buffer to append to the end of this buffer.

Add bytes at the end of the Buffer. Any call to this method invalidates any Iterator pointing to this Buffer.

This is an optimization which kicks in when we attempt to aggregate two buffers which contain adjacent zero areas.

Definition at line 402 of file buffer.cc.

References AddAtEnd(), Begin(), CheckInternalState(), CreateFullCopy(), End(), GetSize(), ns3::Buffer::Data::m_count, m_data, ns3::Buffer::Data::m_dirtyEnd, m_end, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, ns3::Buffer::Iterator::Prev(), and ns3::Buffer::Iterator::Write().

Here is the call graph for this function:

bool ns3::Buffer::AddAtStart ( uint32_t start )

Parameters

start size to reserve

Returns: true if the buffer needed resizing, false otherwise.

Add bytes at the start of the Buffer. The content of these bytes is undefined but debugging builds initialize them to 0x33. Any call to this method invalidates any Iterator pointing to this Buffer.

Definition at line 296 of file buffer.cc.

References CheckInternalState(), Create(), GetInternalSize(), LOG_INTERNAL_STATE, ns3::Buffer::Data::m_count, ns3::Buffer::Data::m_data, m_data, ns3::Buffer::Data::m_dirtyEnd, ns3::Buffer::Data::m_dirtyStart, m_end, m_maxZeroAreaStart, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, Recycle(), and visualizer.core::start().

Referenced by ns3::Packet::AddHeader(), ns3::UdpHeader::CalculateHeaderChecksum(), ns3::TcpHeader::CalculateHeaderChecksum(), ns3::Icmpv6Header::CalculatePseudoHeaderChecksum(), CreateFullCopy(), Deserialize(), ns3::PbbTlv::Deserialize(), ns3::BufferTest::DoRun(), TestEmptyOptionField::DoRun(), ns3::dsr::DsrFsHeaderTest::DoRun(), TestOptionWithoutAlignment::DoRun(), TestOptionWithAlignment::DoRun(), TestFulfilledAlignment::DoRun(), ns3::Packet::Packet(), PbbTestCase::PbbTestCase(), ns3::Ipv6ExtensionLooseRouting::Process(), ns3::PbbTlv::SetValue(), PbbTestCase::TestSerialize(), and ns3::PcapFile::Write().

Here is the call graph for this function:

Here is the caller graph for this function:

struct Buffer::Data * ns3::Buffer::Allocate ( uint32_t reqSize )

staticreadprivate

Definition at line 154 of file buffer.cc.

References data, ns3::Buffer::Data::m_count, ns3::Buffer::Data::m_size, and NS_ASSERT.

Referenced by Create().

Here is the caller graph for this function:

Buffer::Iterator ns3::Buffer::Begin ( void ) const

inline

Returns: an Iterator which points to the start of this Buffer.

Definition at line 875 of file buffer.h.

References CheckInternalState(), and NS_ASSERT.

Referenced by AddAtEnd(), ns3::Packet::AddHeader(), ns3::UdpHeader::CalculateHeaderChecksum(), ns3::TcpHeader::CalculateHeaderChecksum(), ns3::Icmpv6Header::CalculatePseudoHeaderChecksum(), CreateFullCopy(), ns3::Ipv6ExtensionHeader::Deserialize(), ns3::dsr::DsrOptionHeader::Deserialize(), ns3::Ipv6OptionHeader::Deserialize(), ns3::dsr::DsrFsHeader::Deserialize(), ns3::OptionField::Deserialize(), ns3::dsr::DsrOptionField::Deserialize(), Deserialize(), ns3::dsr::DsrOptionRerrHeader::Deserialize(), ns3::PbbTlv::Deserialize(), ns3::BufferTest::DoRun(), ns3::PacketMetadata::ItemIterator::Next(), ns3::WifiInformationElement::operator==(), ns3::Packet::Packet(), PbbTestCase::PbbTestCase(), ns3::Packet::PeekHeader(), ns3::Ipv6ExtensionLooseRouting::Process(), ns3::Packet::RemoveHeader(), ns3::Ipv6OptionHeader::Serialize(), ns3::dsr::DsrOptionHeader::Serialize(), ns3::OptionField::Serialize(), ns3::dsr::DsrOptionField::Serialize(), ns3::dsr::DsrOptionRerrHeader::Serialize(), ns3::PbbTlv::SetValue(), PbbTestCase::TestDeserialize(), PbbTestCase::TestSerialize(), and ns3::PcapFile::Write().

Here is the call graph for this function:

Here is the caller graph for this function:

bool ns3::Buffer::CheckInternalState ( void ) const

private

Definition at line 199 of file buffer.cc.

References LOG_INTERNAL_STATE, ns3::Buffer::Data::m_count, m_data, ns3::Buffer::Data::m_dirtyEnd, ns3::Buffer::Data::m_dirtyStart, m_end, ns3::Buffer::Data::m_size, m_start, m_zeroAreaEnd, and m_zeroAreaStart.

Referenced by AddAtEnd(), AddAtStart(), Begin(), Buffer(), CreateFragment(), CreateFullCopy(), End(), Initialize(), operator=(), PeekData(), RemoveAtEnd(), RemoveAtStart(), TransformIntoRealBuffer(), and ~Buffer().

Here is the caller graph for this function:

void ns3::Buffer::CopyData	(	std::ostream *	os,
		uint32_t	size
	)		const

Copy the specified amount of data from the buffer to the given output stream.

Parameters

os	the output stream
size	the maximum amount of bytes to copy. If zero, nothing is copied.

Definition at line 725 of file buffer.cc.

References anonymous_namespace{buffer.cc}::Zeroes::buffer, anonymous_namespace{buffer.cc}::g_zeroes, ns3::Buffer::Data::m_data, m_data, m_end, m_start, m_zeroAreaEnd, m_zeroAreaStart, and anonymous_namespace{buffer.cc}::Zeroes::size.

Referenced by ns3::Packet::CopyData(), and ns3::PcapFile::Write().

Here is the caller graph for this function:

uint32_t ns3::Buffer::CopyData	(	uint8_t *	buffer,
		uint32_t	size
	)		const

Definition at line 753 of file buffer.cc.

References anonymous_namespace{buffer.cc}::Zeroes::buffer, anonymous_namespace{buffer.cc}::g_zeroes, ns3::Buffer::Data::m_data, m_data, m_end, m_start, m_zeroAreaEnd, m_zeroAreaStart, and anonymous_namespace{buffer.cc}::Zeroes::size.

Buffer::Data * ns3::Buffer::Create ( uint32_t size )

staticreadprivate

Definition at line 147 of file buffer.cc.

References Allocate().

Referenced by AddAtEnd(), AddAtStart(), and Initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

Buffer ns3::Buffer::CreateFragment	(	uint32_t	start,
		uint32_t	length
	)		const

Parameters

start	offset from start of packet
length

Returns: a fragment of size length starting at offset start.

Definition at line 524 of file buffer.cc.

References CheckInternalState(), GetSize(), NS_ASSERT, NS_LOG_FUNCTION, RemoveAtEnd(), and RemoveAtStart().

Referenced by ns3::Packet::CreateFragment(), and ns3::BufferTest::DoRun().

Here is the call graph for this function:

Here is the caller graph for this function:

Buffer ns3::Buffer::CreateFullCopy ( void ) const

Definition at line 536 of file buffer.cc.

References AddAtEnd(), AddAtStart(), Begin(), CheckInternalState(), End(), ns3::Buffer::Data::m_data, m_data, m_end, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, ns3::Buffer::Iterator::Prev(), ns3::Buffer::Iterator::Write(), and ns3::Buffer::Iterator::WriteU8().

Referenced by AddAtEnd(), and TransformIntoRealBuffer().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::Buffer::Deallocate ( struct Buffer::Data * data )

staticprivate

Definition at line 170 of file buffer.cc.

References data, ns3::Buffer::Data::m_count, and NS_ASSERT.

Referenced by Recycle().

Here is the caller graph for this function:

uint32_t ns3::Buffer::Deserialize	(	const uint8_t *	buffer,
		uint32_t	size
	)

Returns: zero if a complete buffer is not deserialized

Parameters

buffer	points to buffer for deserialization
size	number of bytes to deserialize

The raw character buffer is deserialized and all the data is placed into this buffer.

Definition at line 651 of file buffer.cc.

References AddAtEnd(), AddAtStart(), Begin(), End(), Initialize(), NS_ASSERT, ns3::Buffer::Iterator::Prev(), and ns3::Buffer::Iterator::Write().

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

Here is the call graph for this function:

Here is the caller graph for this function:

Buffer::Iterator ns3::Buffer::End ( void ) const

inline

Returns: an Iterator which points to the end of this Buffer.

Definition at line 881 of file buffer.h.

References CheckInternalState(), and NS_ASSERT.

Referenced by AddAtEnd(), ns3::dsr::DsrOptionField::AddDsrOption(), ns3::OptionField::AddOption(), ns3::Packet::AddTrailer(), CreateFullCopy(), Deserialize(), ns3::BufferTest::DoRun(), ns3::PacketMetadata::ItemIterator::Next(), ns3::Packet::PeekTrailer(), ns3::Packet::RemoveTrailer(), ns3::dsr::DsrOptionHeader::Serialize(), ns3::Ipv6OptionHeader::Serialize(), ns3::OptionField::Serialize(), ns3::dsr::DsrOptionField::Serialize(), and ns3::dsr::DsrOptionRerrHeader::Serialize().

Here is the call graph for this function:

Here is the caller graph for this function:

int32_t ns3::Buffer::GetCurrentEndOffset ( void ) const

Definition at line 699 of file buffer.cc.

References m_end.

Referenced by ns3::Packet::AddAtEnd(), ns3::Packet::AddByteTag(), ns3::Packet::AddPaddingAtEnd(), ns3::Packet::AddTrailer(), and ns3::Packet::GetByteTagIterator().

Here is the caller graph for this function:

int32_t ns3::Buffer::GetCurrentStartOffset ( void ) const

Definition at line 694 of file buffer.cc.

References m_start.

Referenced by ns3::Packet::AddAtEnd(), ns3::Packet::AddByteTag(), ns3::Packet::AddHeader(), ns3::Packet::AddTrailer(), ns3::Packet::GetByteTagIterator(), and ns3::Packet::PeekData().

Here is the caller graph for this function:

uint32_t ns3::Buffer::GetInternalEnd ( void ) const

private

Definition at line 290 of file buffer.cc.

References m_end, m_zeroAreaEnd, and m_zeroAreaStart.

Referenced by AddAtEnd().

Here is the caller graph for this function:

uint32_t ns3::Buffer::GetInternalSize ( void ) const

private

Definition at line 285 of file buffer.cc.

References m_end, m_start, m_zeroAreaEnd, and m_zeroAreaStart.

Referenced by AddAtEnd(), and AddAtStart().

Here is the caller graph for this function:

uint32_t ns3::Buffer::GetSerializedSize ( void ) const

Returns: the number of bytes required for serialization

Definition at line 561 of file buffer.cc.

References m_end, m_start, m_zeroAreaEnd, and m_zeroAreaStart.

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

Here is the caller graph for this function:

uint32_t ns3::Buffer::GetSize ( void ) const

inline

Returns: the number of bytes stored in this buffer.

Definition at line 869 of file buffer.h.

References m_end, and m_start.

Referenced by ns3::Packet::AddAtEnd(), AddAtEnd(), ns3::OptionField::CalculatePad(), ns3::dsr::DsrOptionField::CalculatePad(), ns3::Packet::CreateFragment(), CreateFragment(), ns3::Ipv6ExtensionHeader::Deserialize(), ns3::dsr::DsrFsHeader::Deserialize(), ns3::BufferTest::DoRun(), ns3::OptionField::GetSerializedSize(), ns3::dsr::DsrOptionField::GetSerializedSize(), ns3::PbbTlv::GetSerializedSize(), ns3::Packet::GetSize(), ns3::PacketMetadata::ItemIterator::Next(), ns3::PbbTlv::operator==(), ns3::PbbTlv::Print(), ns3::Ipv6ExtensionHeader::Serialize(), ns3::dsr::DsrFsHeader::Serialize(), ns3::PbbTlv::Serialize(), PbbTestCase::TestDeserialize(), PbbTestCase::TestSerialize(), and ns3::PbbTlv::~PbbTlv().

Here is the caller graph for this function:

void ns3::Buffer::Initialize ( uint32_t zeroSize )

private

Definition at line 232 of file buffer.cc.

References CheckInternalState(), Create(), g_recommendedStart, m_data, ns3::Buffer::Data::m_dirtyEnd, ns3::Buffer::Data::m_dirtyStart, m_end, m_maxZeroAreaStart, ns3::Buffer::Data::m_size, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by Buffer(), and Deserialize().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Definition at line 247 of file buffer.cc.

References CheckInternalState(), g_recommendedStart, ns3::Buffer::Data::m_count, m_data, m_end, m_maxZeroAreaStart, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, and Recycle().

Here is the call graph for this function:

uint8_t const * ns3::Buffer::PeekData ( void ) const

Returns: a pointer to the start of the internal byte buffer.

The returned pointer points to an area of memory which is ns3::Buffer::GetSize () bytes big. Please, try to never ever use this method. It is really evil and is present only for a few specific uses.

Definition at line 716 of file buffer.cc.

References CheckInternalState(), ns3::Buffer::Data::m_data, m_data, m_start, NS_ASSERT, and TransformIntoRealBuffer().

Referenced by ns3::BufferTest::DoRun(), ns3::BufferTest::EnsureWrittenBytes(), ns3::WifiInformationElement::operator==(), ns3::PbbTlv::operator==(), ns3::Packet::PeekData(), ns3::Ipv6ExtensionHeader::Serialize(), ns3::dsr::DsrFsHeader::Serialize(), and PbbTestCase::TestSerialize().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::Buffer::Recycle ( struct Buffer::Data * data )

staticprivate

Definition at line 140 of file buffer.cc.

References Deallocate(), ns3::Buffer::Data::m_count, and NS_ASSERT.

Referenced by AddAtEnd(), AddAtStart(), operator=(), and ~Buffer().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::Buffer::RemoveAtEnd ( uint32_t end )

Parameters

end	size to remove

Remove bytes at the end of the Buffer. Any call to this method invalidates any Iterator pointing to this Buffer.

Definition at line 488 of file buffer.cc.

References CheckInternalState(), LOG_INTERNAL_STATE, m_end, m_maxZeroAreaStart, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, and NS_LOG_FUNCTION.

Referenced by CreateFragment(), ns3::Ipv6ExtensionHeader::Deserialize(), ns3::dsr::DsrFsHeader::Deserialize(), ns3::BufferTest::DoRun(), ns3::PacketMetadata::ItemIterator::Next(), ns3::Packet::RemoveAtEnd(), ns3::Packet::RemoveTrailer(), and ns3::PbbTlv::~PbbTlv().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::Buffer::RemoveAtStart ( uint32_t start )

Parameters

start size to remove

Remove bytes at the start of the Buffer. Any call to this method invalidates any Iterator pointing to this Buffer.

Definition at line 443 of file buffer.cc.

References CheckInternalState(), LOG_INTERNAL_STATE, m_end, m_maxZeroAreaStart, m_start, m_zeroAreaEnd, m_zeroAreaStart, NS_ASSERT, NS_LOG_FUNCTION, and visualizer.core::start().

Referenced by CreateFragment(), ns3::BufferTest::DoRun(), ns3::PacketMetadata::ItemIterator::Next(), ns3::Packet::RemoveAtStart(), and ns3::Packet::RemoveHeader().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t ns3::Buffer::Serialize	(	uint8_t *	buffer,
		uint32_t	maxSize
	)		const

Returns: zero if buffer not large enough

Parameters

buffer	points to serialization buffer
maxSize	max number of bytes to write

This buffer's contents are serialized into the raw character buffer parameter. Note: The zero length data is not copied entirely. Only the length of zero byte data is serialized.

Definition at line 580 of file buffer.cc.

References ns3::Buffer::Data::m_data, m_data, m_end, m_start, m_zeroAreaEnd, m_zeroAreaStart, and NS_LOG_FUNCTION.

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

Here is the caller graph for this function: