Message is a reusable and resizable data buffer for sending and receiving messages. More...

#include <Message.h>

Inheritance diagram for Message:

[legend]

Public Types
enum	{ DefaultCapacity = 4096 }
enum	Service { Unreliable = UNRELIABLE_MESS, Reliable = RELIABLE_MESS, FIFO = FIFO_MESS, Causal = CAUSAL_MESS, Agreed = AGREED_MESS, Safe = SAFE_MESS, SelfDiscard = SELF_DISCARD, DropReceive = DROP_RECV }
	Service is not a proper enumeration, but rather a specification of constants corresponding to the Spread service type flags. More...
typedef Spread::int16	message_type
	Defines the type for 16-bit message type identifiers.
typedef Spread::service	service_type
	Defines the type for specifying service types.
typedef char	value_type
typedef value_type &	reference
typedef const reference	const_reference
typedef value_type *	pointer
typedef const value_type *	const_pointer
typedef pointer	iterator
typedef const_pointer	const_iterator
typedef std::reverse_iterator < iterator >	reverse_iterator
typedef std::reverse_iterator < const_iterator >	const_reverse_iterator
Public Member Functions
	Message (const unsigned int capacity=DefaultCapacity)
	Creates a Message with the specified initial capacity (or DefaultCapacity if no parameter is provided).
virtual unsigned int	size () const
	Returns the number of bytes in the message.
virtual void	clear ()
	Clears the message for reuse, resetting its size to zero.
void	set_service (const service_type service)
	Sets the service type of the message.
service_type	service () const
	Returns the service type requested (for sends) or sent under (for receives) of the message.
void	set_type (const message_type type)
	Sets the message type identifier.
message_type	type () const
	Returns the type of the message.
void	set_sender (const string &sender)
	Sets the message sender.
const string &	sender () const
	Returns the message sender.
void	set_endian_mismatch (const bool mismatch=true)
	Sets the endian mismatch flag to the specified value.
bool	endian_mismatch () const
	Returns true if there is an endian mismatch between sender and receiver, false otherwise.
void	set_agreed ()
	Sets the service type to BaseMessage::Agreed.
bool	is_agreed () const
	Returns true if service type is BaseMessage::Agreed, false otherwise.
void	set_causal ()
	Sets the service type to BaseMessage::Causal.
bool	is_causal () const
	Returns true if service type is BaseMessage::Causal, false otherwise.
void	set_fifo ()
	Sets the service type to BaseMessage::FIFO.
bool	is_fifo () const
	Returns true if service type is BaseMessage::FIFO, false otherwise.
void	set_reliable ()
	Sets the service type to BaseMessage::Reliable.
bool	is_reliable () const
	Returns true if service type is BaseMessage::Reliable, false otherwise.
void	set_unreliable ()
	Sets the service type to BaseMessage::Unreliable.
bool	is_unreliable () const
	Returns true if service type is BaseMessage::Unreliable, false otherwise.
void	set_safe ()
	Sets the service type to BaseMessage::Safe.
bool	is_safe () const
	Returns true if service type is BaseMessage::Safe, false otherwise.
void	set_self_discard (const bool discard=true)
	Adds or removes the BaseMessage::SelfDiscard flag to or from the service type.
bool	is_self_discard () const
	Returns true if service type has the BaseMessage::SelfDiscard flag set, false otherwise.
bool	is_regular () const
	Returns true if this is a regular data (as opposed to membership) message, false otherwise.
bool	is_membership () const
	Returns true if this is a membership message, false otherwise.
unsigned int	offset () const
	Returns the current read/write position.
unsigned int	seek (const unsigned int offset)
	Sets the read/write position to the specified value if the value is less than or equal to the size of the buffer.
void	rewind ()
	Same as seek(0).
void	write (const void *data, const unsigned int size)
	Writes the specified number of bytes from the provided data into the buffer at the current read/write position.
unsigned int	read (void *data, unsigned int size)
	Reads the specified number of bytes from the buffer into the provided destination starting from the current read/write position.
unsigned int	capacity () const
	Returns the maximum number of elements that can be written to the buffer without reallocating memory.
reference	operator[] (const unsigned int index)
	Returns the element at the specified index.
const_reference	operator[] (const unsigned int index) const
	Returns the element at the specified index.
iterator	begin ()
	Returns an iterator pointing to the first element in the buffer.
const_iterator	begin () const
	Returns a const iterator pointing to the first element in the buffer.
iterator	end ()
	Returns an iterator pointing to one position beyond the last element in the buffer.
const_iterator	end () const
	Returns an iterator pointing to one position beyond the last element in the buffer.
reverse_iterator	rbegin ()
	Returns reverse_iterator(end()).
const_reverse_iterator	rbegin () const
	Returns const_reverse_iterator(end()).
reverse_iterator	rend ()
	Returns reverse_iterator(begin()).
const_reverse_iterator	rend () const
	Returns const_reverse_iterator(begin()).
void	reserve (const unsigned int capacity)
	Increases the buffer capacity to the specified size.
void	resize (const unsigned int size)
	Resizes the buffer to the specified size.
void	add (const char &value)
	Appends a value to the end of the buffer and increments the size by one.
Protected Attributes
message_type	_type
service_type	_service_type
bool	_endian_mismatch
string	_sender

Detailed Description

Message is a reusable and resizable data buffer for sending and receiving messages.

We do not document its protected members because they are intended only for internal library use. All of its useful public methods are inherited from BaseMessage and detail::ByteBuffer.

Please note that you can directly access the message data via indexing with detail::Buffer::operator[] or obtaining a pointer to the data via:

&message[0]

Therefore, you will find you do not have to use detail::ByteBuffer::read unless you really have to make a copy of the data instead of using it directly. However, you should use detail::ByteBuffer::write to avoid overrunning the buffer.

Definition at line 47 of file Message.h.

Member Typedef Documentation

typedef const_pointer detail::Buffer< char >::const_iterator [inherited]

Definition at line 62 of file Buffer.h.

typedef const value_type* detail::Buffer< char >::const_pointer [inherited]

Definition at line 60 of file Buffer.h.

typedef const reference detail::Buffer< char >::const_reference [inherited]

Definition at line 58 of file Buffer.h.

typedef std::reverse_iterator<const_iterator> detail::Buffer< char >::const_reverse_iterator [inherited]

Definition at line 64 of file Buffer.h.

typedef pointer detail::Buffer< char >::iterator [inherited]

Definition at line 61 of file Buffer.h.

typedef Spread::int16 BaseMessage::message_type [inherited]

Defines the type for 16-bit message type identifiers.

Definition at line 61 of file BaseMessage.h.

typedef value_type* detail::Buffer< char >::pointer [inherited]

Definition at line 59 of file Buffer.h.

typedef value_type& detail::Buffer< char >::reference [inherited]

Definition at line 57 of file Buffer.h.

typedef std::reverse_iterator<iterator> detail::Buffer< char >::reverse_iterator [inherited]

Definition at line 63 of file Buffer.h.

typedef Spread::service BaseMessage::service_type [inherited]

Defines the type for specifying service types.

Definition at line 64 of file BaseMessage.h.

typedef char detail::Buffer< char >::value_type [inherited]

Definition at line 56 of file Buffer.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

DefaultCapacity

The default capacity used to construct a Message.

Definition at line 80 of file Message.h.

enum BaseMessage::Service [inherited]

Service is not a proper enumeration, but rather a specification of constants corresponding to the Spread service type flags.

We do not document the meaning of these flags here. See the Spread C API documentation to understand their meaning. We will note, however, that DropReceive is not a service type, but rather a flag instructing the Spread receive functions to truncate messages and group lists if the buffers are too small. There should be no need to use this constant in the API as it is handled by Mailbox::set_drop_receive.

Enumerator:

Unreliable
Reliable
FIFO
Causal
Agreed
Safe
SelfDiscard
DropReceive

Definition at line 79 of file BaseMessage.h.

Constructor & Destructor Documentation

Message::Message ( const unsigned int capacity = DefaultCapacity ) [inline, explicit]

Creates a Message with the specified initial capacity (or DefaultCapacity if no parameter is provided).

See BaseMessage() for the default values of various properties, including service type.

Parameters:

capacity The initial capacity of the message.

Definition at line 93 of file Message.h.

Member Function Documentation

void detail::Buffer< char >::add ( const char & value ) [inline, inherited]

Appends a value to the end of the buffer and increments the size by one.

If the buffer is at full capacity, its capacity is increased to be able to hold more data. Currently, this is done by doubling the current capacity, but you should not rely on that behavior.

Parameters:

value The value to append to the buffer.

Definition at line 241 of file Buffer.h.

References detail::Buffer< type >::capacity(), and detail::Buffer< type >::reserve().

iterator detail::Buffer< char >::begin ( ) [inline, inherited]

Returns an iterator pointing to the first element in the buffer.

Returns:: An iterator pointing to the first element in the buffer.

Definition at line 115 of file Buffer.h.

const_iterator detail::Buffer< char >::begin ( ) const [inline, inherited]

Returns a const iterator pointing to the first element in the buffer.

Returns:: A const iterator pointing to the first element in the buffer.

Definition at line 124 of file Buffer.h.

unsigned int detail::Buffer< char >::capacity ( ) const [inline, inherited]

Returns the maximum number of elements that can be written to the buffer without reallocating memory.

Returns:: The buffer capacity.

Definition at line 86 of file Buffer.h.

virtual void Message::clear ( ) [inline, virtual]

Clears the message for reuse, resetting its size to zero.

Implements BaseMessage.

Definition at line 100 of file Message.h.

iterator detail::Buffer< char >::end ( ) [inline, inherited]

Returns an iterator pointing to one position beyond the last element in the buffer.

Returns:: An iterator pointing to one position beyond the last element in the buffer.

Definition at line 135 of file Buffer.h.

const_iterator detail::Buffer< char >::end ( ) const [inline, inherited]

Returns an iterator pointing to one position beyond the last element in the buffer.

Returns:: An iterator pointing to one position beyond the last element in the buffer.

Definition at line 146 of file Buffer.h.

bool BaseMessage::endian_mismatch ( ) const [inline, inherited]

Returns true if there is an endian mismatch between sender and receiver, false otherwise.

This only has meaning for received messages.

Returns:: true if there is an endian mismatch between sender and receiver, false otherwise.

Definition at line 225 of file BaseMessage.h.

References BaseMessage::_endian_mismatch.

bool BaseMessage::is_agreed ( ) const [inline, inherited]

Returns true if service type is BaseMessage::Agreed, false otherwise.

Returns:: true if service type is BaseMessage::Agreed, false otherwise.

Definition at line 238 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_causal ( ) const [inline, inherited]

Returns true if service type is BaseMessage::Causal, false otherwise.

Returns:: true if service type is BaseMessage::Causal, false otherwise.

Definition at line 251 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_fifo ( ) const [inline, inherited]

Returns true if service type is BaseMessage::FIFO, false otherwise.

Returns:: true if service type is BaseMessage::FIFO, false otherwise.

Definition at line 264 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_membership ( ) const [inline, inherited]

Returns true if this is a membership message, false otherwise.

Returns:: true if this is a membership message, false otherwise.

Definition at line 343 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_regular ( ) const [inline, inherited]

Returns true if this is a regular data (as opposed to membership) message, false otherwise.

Returns:: true if this is a regular message, false otherwise.

Definition at line 335 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_reliable ( ) const [inline, inherited]

Returns true if service type is BaseMessage::Reliable, false otherwise.

Returns:: true if service type is BaseMessage::Reliable, false otherwise.

Definition at line 277 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_safe ( ) const [inline, inherited]

Returns true if service type is BaseMessage::Safe, false otherwise.

Returns:: true if service type is BaseMessage::Safe, false otherwise.

Definition at line 303 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_self_discard ( ) const [inline, inherited]

Returns true if service type has the BaseMessage::SelfDiscard flag set, false otherwise.

Returns:: true if service type has the BaseMessage::SelfDiscard flag set, false otherwise.

Definition at line 326 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_unreliable ( ) const [inline, inherited]

Returns true if service type is BaseMessage::Unreliable, false otherwise.

Returns:: true if service type is BaseMessage::Unreliable, false otherwise.

Definition at line 290 of file BaseMessage.h.

References BaseMessage::service().

unsigned int detail::ByteBuffer::offset ( ) const [inline, inherited]

Returns the current read/write position.

Returns:: The current read/write position.

Definition at line 93 of file ByteBuffer.h.

Referenced by detail::ByteBuffer::ByteBuffer(), detail::ByteBuffer::operator=(), and detail::ByteBuffer::seek().

reference detail::Buffer< char >::operator[] ( const unsigned int index ) [inline, inherited]

Returns the element at the specified index.

Parameters:

index The index of the element to retrieve.

Returns:: The element at the specified index.

Definition at line 96 of file Buffer.h.

const_reference detail::Buffer< char >::operator[] ( const unsigned int index ) const [inline, inherited]

Returns the element at the specified index.

Parameters:

index The index of the element to retrieve.

Returns:: The element at the specified index.

Definition at line 106 of file Buffer.h.

reverse_iterator detail::Buffer< char >::rbegin ( ) [inline, inherited]

Returns reverse_iterator(end()).

Returns:: reverse_iterator(end()).

Definition at line 155 of file Buffer.h.

References detail::Buffer< type >::end().

const_reverse_iterator detail::Buffer< char >::rbegin ( ) const [inline, inherited]

Returns const_reverse_iterator(end()).

Returns:: const_reverse_iterator(end()).

Definition at line 164 of file Buffer.h.

References detail::Buffer< type >::end().

unsigned int detail::ByteBuffer::read	(	void *	data,
		unsigned int	size
	)		`[inline, inherited]`

Reads the specified number of bytes from the buffer into the provided destination starting from the current read/write position.

If the number of bytes to be read would result in running off the end of the buffer, the read is truncated at the end of the buffer.

Parameters:

data	A pointer to the read destination.
size	The number of bytes to read.

Returns:: The number of bytes read.

Definition at line 157 of file ByteBuffer.h.

References detail::Buffer< char >::size().

reverse_iterator detail::Buffer< char >::rend ( ) [inline, inherited]

Returns reverse_iterator(begin()).

Returns:: reverse_iterator(begin()).

Definition at line 173 of file Buffer.h.

References detail::Buffer< type >::begin().

const_reverse_iterator detail::Buffer< char >::rend ( ) const [inline, inherited]

Returns const_reverse_iterator(begin()).

Returns:: const_reverse_iterator(begin()).

Definition at line 182 of file Buffer.h.

References detail::Buffer< type >::begin().

void detail::Buffer< char >::reserve ( const unsigned int capacity ) [inline, inherited]

Increases the buffer capacity to the specified size.

If the new size is less than or equal to the buffer capacity, no action is performed. If the size is greater than the capacity, new memory is reserved, increasing the capacity while preserving the existing buffer contents.

Parameters:

capacity The new buffer capacity.

Definition at line 195 of file Buffer.h.

References detail::Buffer< type >::capacity().

Referenced by detail::ByteBuffer::ByteBuffer().

void detail::Buffer< char >::resize ( const unsigned int size ) [inline, inherited]

Resizes the buffer to the specified size.

If the new size is less than or equal to the buffer capacity, the size is simply set to the new value. If the size is greater than the capacity, new memory is reserved—preserving the existing buffer contents—before setting the size to the new value.

Parameters:

size	The new buffer size.

Definition at line 214 of file Buffer.h.

References detail::Buffer< type >::reserve(), and detail::Buffer< type >::size().

Referenced by detail::ByteBuffer::clear(), and detail::ByteBuffer::write().

void detail::ByteBuffer::rewind ( ) [inline, inherited]

Same as seek(0).

Definition at line 112 of file ByteBuffer.h.

References detail::ByteBuffer::seek().

Referenced by detail::ByteBuffer::clear().

unsigned int detail::ByteBuffer::seek ( const unsigned int offset ) [inline, inherited]

Sets the read/write position to the specified value if the value is less than or equal to the size of the buffer.

Otherwise, the current offset is left unchanged.

Parameters:

offset The buffer offset of the new read/write position.

Returns:: The new read/write position.

Definition at line 105 of file ByteBuffer.h.

References detail::ByteBuffer::offset(), and detail::Buffer< char >::size().

Referenced by detail::ByteBuffer::ByteBuffer(), detail::ByteBuffer::operator=(), and detail::ByteBuffer::rewind().

const string& BaseMessage::sender ( ) const [inline, inherited]

Returns the message sender.

This only has meaning for received messages.

Returns:: The message sender.

Definition at line 207 of file BaseMessage.h.

References BaseMessage::_sender.

Referenced by BaseMessage::set_sender().

service_type BaseMessage::service ( ) const [inline, inherited]

Returns the service type requested (for sends) or sent under (for receives) of the message.

Returns:: The service type of the message.

Definition at line 175 of file BaseMessage.h.

References BaseMessage::_service_type.

Referenced by BaseMessage::is_agreed(), BaseMessage::is_causal(), BaseMessage::is_fifo(), BaseMessage::is_membership(), BaseMessage::is_regular(), BaseMessage::is_reliable(), BaseMessage::is_safe(), BaseMessage::is_self_discard(), BaseMessage::is_unreliable(), and BaseMessage::set_service().

void BaseMessage::set_agreed ( ) [inline, inherited]

Sets the service type to BaseMessage::Agreed.

Definition at line 230 of file BaseMessage.h.

References BaseMessage::Agreed, and BaseMessage::set_service().

void BaseMessage::set_causal ( ) [inline, inherited]

Sets the service type to BaseMessage::Causal.

Definition at line 243 of file BaseMessage.h.

References BaseMessage::Causal, and BaseMessage::set_service().

void BaseMessage::set_endian_mismatch ( const bool mismatch = true ) [inline, inherited]

Sets the endian mismatch flag to the specified value.

Parameters:

mismatch The mismatch value.

Definition at line 215 of file BaseMessage.h.

References BaseMessage::_endian_mismatch.

void BaseMessage::set_fifo ( ) [inline, inherited]

Sets the service type to BaseMessage::FIFO.

Definition at line 256 of file BaseMessage.h.

References BaseMessage::FIFO, and BaseMessage::set_service().

void BaseMessage::set_reliable ( ) [inline, inherited]

Sets the service type to BaseMessage::Reliable.

Definition at line 269 of file BaseMessage.h.

References BaseMessage::Reliable, and BaseMessage::set_service().

void BaseMessage::set_safe ( ) [inline, inherited]

Sets the service type to BaseMessage::Safe.

Definition at line 295 of file BaseMessage.h.

References BaseMessage::Safe, and BaseMessage::set_service().

void BaseMessage::set_self_discard ( const bool discard = true ) [inline, inherited]

Adds or removes the BaseMessage::SelfDiscard flag to or from the service type.

Parameters:

discard true to set the BaseMessage::SelfDiscard flag, false to remove it.

Definition at line 314 of file BaseMessage.h.

References BaseMessage::_service_type, and BaseMessage::SelfDiscard.

void BaseMessage::set_sender ( const string & sender ) [inline, inherited]

Sets the message sender.

Parameters:

sender The message sender.

Definition at line 199 of file BaseMessage.h.

References BaseMessage::_sender, and BaseMessage::sender().

void BaseMessage::set_service ( const service_type service ) [inline, inherited]

Sets the service type of the message.

Parameters:

service The service type of the message.

Definition at line 165 of file BaseMessage.h.

References BaseMessage::_service_type, and BaseMessage::service().

Referenced by Mailbox::send(), BaseMessage::set_agreed(), BaseMessage::set_causal(), BaseMessage::set_fifo(), BaseMessage::set_reliable(), BaseMessage::set_safe(), and BaseMessage::set_unreliable().

void BaseMessage::set_type ( const message_type type ) [inline, inherited]

Sets the message type identifier.

Parameters:

type	The new message type.

Definition at line 183 of file BaseMessage.h.

References BaseMessage::_type, and BaseMessage::type().

Referenced by Mailbox::send().

void BaseMessage::set_unreliable ( ) [inline, inherited]

Sets the service type to BaseMessage::Unreliable.

Definition at line 282 of file BaseMessage.h.

References BaseMessage::set_service(), and BaseMessage::Unreliable.

virtual unsigned int Message::size ( ) const [inline, virtual]

Returns the number of bytes in the message.

Returns:: The number of bytes in the message.

Implements BaseMessage.

Definition at line 96 of file Message.h.

Referenced by ScatterMessage::add().

message_type BaseMessage::type ( ) const [inline, inherited]

Returns the type of the message.

Returns:: The type of the message.

Definition at line 191 of file BaseMessage.h.

References BaseMessage::_type.

Referenced by BaseMessage::set_type().

void detail::ByteBuffer::write	(	const void *	data,
		const unsigned int	size
	)		`[inline, inherited]`

Writes the specified number of bytes from the provided data into the buffer at the current read/write position.

If the buffer is not large enough to hold the data, it is resized automatically to the current offset plus the size of the data to be written. After writing the data, the read/write position is incremented by the size of the data written.

Parameters: