A utility class which generates a MtCollatedPacket message by appending multiple other messages. More...

#include <3escollatedpacket.h>

Inheritance diagram for tes::CollatedPacket:

Public Member Functions
	CollatedPacket (bool compress, uint16_t bufferSize=0xff00u)
	Initialise a collated packet. More...

	CollatedPacket (unsigned bufferSize, unsigned maxPacketSize)
	Initialise a collated packet allowing packet sizes large than `MaxPacketSize`. More...

	~CollatedPacket ()
	Destructor.

bool	compressionEnabled () const
	Is compression enabled. More...

unsigned	maxPacketSize () const
	Return the capacity of the collated packet. More...

void	reset ()
	Reset the collated packet, dropping any existing data.

int	add (const PacketWriter &packet)
	Add the packet data in `packet` to the collation buffer. More...

int	add (const uint8_t *buffer, uint16_t byteCount)
	Add bytes to the packet. More...

bool	finalise ()
	Finalises the collated packet for sending. More...

const uint8_t *	buffer (unsigned &byteCount) const
	Access the internal buffer pointer. More...

unsigned	collatedBytes () const
	Return the number of bytes that have been collated. More...

void	close () override
	Ignored for `CollatedPacket`.

void	setActive (bool active) override
	Enable/disable the connection. More...

bool	active () const override
	Check if currently active. More...

const char *	address () const override
	Identifies the collated packet. More...

uint16_t	port () const override
	Not supported. More...

bool	isConnected () const override
	Always connected. More...

int	create (const Shape &shape) override
	Collated the create message for `shape`. More...

int	destroy (const Shape &shape) override
	Collated the update message for `shape`. More...

int	update (const Shape &shape) override
	Collated the destroy message for `shape`. More...

int	updateTransfers (unsigned byteLimit) override
	Not supported. More...

int	updateFrame (float dt, bool flush=true) override
	Not supported. More...

unsigned	referenceResource (const Resource *resource) override
	Not supported. More...

unsigned	releaseResource (const Resource *resource) override
	Not supported. More...

bool	sendServerInfo (const ServerInfoMessage &info) override
	Collated the create message for `shape`. More...

int	send (const uint8_t *data, int byteCount) override
	Aliased to `add()`. More...

Public Member Functions inherited from tes::Connection
virtual	~Connection ()
	Virtual destructor.

int	send (const int8_t *data, int byteCount)

Static Public Attributes
static const size_t	Overhead
	Byte count overhead added by using a `CollatedPacket`. More...

static const unsigned	InitialCursorOffset
	Initial cursor position in the write buffer. More...

static const uint16_t	MaxPacketSize
	The default packet size limit for a `CollatedPacketMessage`.

Detailed Description

A utility class which generates a MtCollatedPacket message by appending multiple other messages.

Compression may optionally be applied.

Typical usage:

Instantiate the packet.
Reset the packet.
For each constituent message
- Generate the packet using PacketWriter.
- Finalise the message.
- Call add(const PacketWriter &)
Call finalise() on the collated packet.
Send the collated packet.
Call reset()

The CollatedPacket also extends the Connection class in order to support multi-threaded packet generation and synchronisation. While the Connection and Connection implementations are required to be thread-safe, they cannot guarantee packets area correctly collated by thread. Thus a CollatedPacket can be used per thread to collate messages for each thread. The packet content can then be sent as a single transaction.

By supporting the Connection methods, a CollatedPacket can be used in place of a 'server' argument with various server utility macros and functions.

By default, a CollatedPacket has is limited to supporting MaxPacketSize bytes. This allows a single packet with a single PacketHeader and collated packet message with optional compression. However, when a collated packet is used for transaction collation (as described in the multi-threaded case), it may require collation of larger data sizes. In this case, the CollatedPacket(unsigned, unsigned) constructor can be used to specify a larger collation buffer limit (the buffer resizes as required). Such large, collated packets are sent using Server::send(const CollatedPacket &). Internally, the method may either send the packet as is (if small enough), or extract and reprocess each collated packet.

Constructor & Destructor Documentation

◆ CollatedPacket() [1/2]

tes::CollatedPacket::CollatedPacket	(	bool	compress,
		uint16_t	bufferSize = `0xff00u`
	)

Initialise a collated packet.

This sets the initial packet size limited by MaxPacketSize, and compression options.

Parameters

compress	True to compress data as written.
bufferSize	The initial bufferSize

Bug:: Specifying a buffer size too close to 0xffff (even correctly accounting for the expected overhead) results in dropped packets despite the network layer not reporting errors. Likely I'm missing some overhead detail. For now, use a lower packet size.

◆ CollatedPacket() [2/2]

tes::CollatedPacket::CollatedPacket	(	unsigned	bufferSize,
		unsigned	maxPacketSize
	)

Initialise a collated packet allowing packet sizes large than MaxPacketSize.

This is intended for collating messages to be send as a group in a thread-safe fashion. The maximum packet size may exceed the normal send limit. As such compression is not allowed to better support splitting.

Parameters

bufferSize	The initial bufferSize
maxPacketSize	The maximum packet size.

Member Function Documentation

◆ active()

bool tes::CollatedPacket::active ( ) const

overridevirtual

Check if currently active.

Returns: True while active.

Implements tes::Connection.

◆ add() [1/2]

int tes::CollatedPacket::add ( const PacketWriter & packet )

Add the packet data in packet to the collation buffer.

The method will fail (return -1) when the maxPacketSize() has been reached. In this case, the packet should be sent and reset before trying again. The method will also fail if the packet has already been finalised using finalise().

Parameters

packet The packet data to add.

Returns: The packet.packetSize() on success, or -1 on failure.

◆ add() [2/2]

int tes::CollatedPacket::add	(	const uint8_t *	buffer,
		uint16_t	byteCount
	)

Add bytes to the packet.

Use with care as the buffer should always start with a valid PacketHeader in network byte order.

Parameters

buffer	The data to add.
byteCount	The number of bytes in `buffer`.

Returns: The packet.packetSize() on success, or -1 on failure.

◆ address()

const char* tes::CollatedPacket::address ( ) const

overridevirtual

Identifies the collated packet.

Returns: Always "CollatedPacket".

Implements tes::Connection.

◆ buffer()

const uint8_t* tes::CollatedPacket::buffer ( unsigned & byteCount ) const

Access the internal buffer pointer.

Parameters

[out] Set to the number of used bytes in the collated buffer, including the CRC when the packet has been finalised.

Returns: The internal buffer pointer.

◆ collatedBytes()

unsigned tes::CollatedPacket::collatedBytes ( ) const

inline

Return the number of bytes that have been collated.

This excludes the PacketHeader and CollatedPacketMessage, but will include the CRC once finalised.

◆ compressionEnabled()

bool tes::CollatedPacket::compressionEnabled ( ) const

inline

Is compression enabled.

Required ZLIB.

Returns: True if compression is enabled.

◆ create()

int tes::CollatedPacket::create ( const Shape & shape )

overridevirtual

Collated the create message for shape.

Parameters

shape The shape of interest.

Returns: The number of bytes added, or -1 on failure (as per add()).

Implements tes::Connection.

◆ destroy()

int tes::CollatedPacket::destroy ( const Shape & shape )

overridevirtual

Collated the update message for shape.

Parameters

shape The shape of interest.

Returns: The number of bytes added, or -1 on failure (as per add()).

Implements tes::Connection.

◆ finalise()

bool tes::CollatedPacket::finalise ( )

Finalises the collated packet for sending.

This includes completing compression and calculating the CRC.

Returns: True on successful finalisation, false when already finalised.

◆ isConnected()

bool tes::CollatedPacket::isConnected ( ) const

overridevirtual

Always connected.

Returns: True.

Implements tes::Connection.

◆ maxPacketSize()

unsigned tes::CollatedPacket::maxPacketSize ( ) const

inline

Return the capacity of the collated packet.

This defaults to 64 * 1024 - 1 (the maximum for a 16-bit unsigned integer), when using the constructor: CollatedPacket(bool, unsigned). It may be larger when using the CollatedPacket(unsigned, unsigned) constructor. See that constructor and class notes for details.

Returns: The maximum packet capacity or 0xffffffffu if the packet size is variable.

◆ port()

uint16_t tes::CollatedPacket::port ( ) const

overridevirtual

Not supported.

Returns: Zero.

Implements tes::Connection.

◆ referenceResource()

unsigned tes::CollatedPacket::referenceResource ( const Resource * resource )

overridevirtual

Not supported.

Returns: 0;

Implements tes::Connection.

◆ releaseResource()

unsigned tes::CollatedPacket::releaseResource ( const Resource * resource )

overridevirtual

Not supported.

Returns: 0;

Implements tes::Connection.

◆ send()

int tes::CollatedPacket::send	(	const uint8_t *	data,
		int	byteCount
	)

overridevirtual

Aliased to add().

Parameters

buffer	The data to add.
bufferSize	The number of bytes in `buffer`.

Returns: The packet.packetSize() on success, or -1 on failure.

Implements tes::Connection.

◆ sendServerInfo()

bool tes::CollatedPacket::sendServerInfo ( const ServerInfoMessage & info )

overridevirtual

Collated the create message for shape.

Parameters

shape The shape of interest.

Returns: The number of bytes added, or -1 on failure (as per add()).

Implements tes::Connection.

◆ setActive()

void tes::CollatedPacket::setActive ( bool active )

overridevirtual

Enable/disable the connection.

While disabled, messages are ignored.

Parameters

active The active state to set.

Implements tes::Connection.

◆ update()

int tes::CollatedPacket::update ( const Shape & shape )

overridevirtual

Collated the destroy message for shape.

Parameters

shape The shape of interest.

Returns: The number of bytes added, or -1 on failure (as per add()).

Implements tes::Connection.

◆ updateFrame()

int tes::CollatedPacket::updateFrame	(	float	dt,
		bool	flush = `true`
	)

overridevirtual

Not supported.

Parameters

dt	Ignored.
flush	Ignored.

Implements tes::Connection.

◆ updateTransfers()

int tes::CollatedPacket::updateTransfers ( unsigned byteLimit )

overridevirtual

Not supported.

Parameters

byteLimit Ignored.

Returns: -1.

Implements tes::Connection.

Member Data Documentation

◆ InitialCursorOffset

const unsigned tes::CollatedPacket::InitialCursorOffset

static

Initial cursor position in the write buffer.

This is the sum of PacketHeader, CollatedPacketMessage.

◆ Overhead

const size_t tes::CollatedPacket::Overhead

static

Byte count overhead added by using a CollatedPacket.

This is the sum of PacketHeader, CollatedPacketMessage and the PacketWriter::CrcType.

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

3escollatedpacket.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CollatedPacket() [1/2]

◆ CollatedPacket() [2/2]

Member Function Documentation

◆ active()

◆ add() [1/2]

◆ add() [2/2]

◆ address()

◆ buffer()

◆ collatedBytes()

◆ compressionEnabled()

◆ create()

◆ destroy()

◆ finalise()

◆ isConnected()

◆ maxPacketSize()

◆ port()

◆ referenceResource()

◆ releaseResource()

◆ send()

◆ sendServerInfo()

◆ setActive()

◆ update()

◆ updateFrame()

◆ updateTransfers()

Member Data Documentation

◆ InitialCursorOffset

◆ Overhead