ssrc::spread::Message Class Reference

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

#include <Message.h>

Inheritance diagram for ssrc::spread::Message:

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 pointer	const_pointer
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	get_membership_info (MembershipInfo &info) const
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.
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 Member Functions
virtual int	sp_get_membership_info (Spread::membership_info *info) const
virtual int	sp_get_vs_set_members (const Spread::vs_set_info *vs_set, Spread::group_type member_names[], unsigned int member_names_count) const
virtual int	sp_get_vs_sets_info (Spread::vs_set_info vs_sets, unsigned int num_vs_sets, unsigned int index) const
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]

You can do this because detail::Buffer is derived from std::vector and we guarantee this behavior is defined even though we do not consider detail::Buffer to be part of the public API. 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 50 of file Message.h.

Member Typedef Documentation

typedef const pointer ssrc::spread::detail::Buffer< char >::const_pointer [inherited]

Definition at line 61 of file Buffer.h.

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

Definition at line 59 of file Buffer.h.

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

Defines the type for 16-bit message type identifiers.

Definition at line 61 of file BaseMessage.h.

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

Definition at line 60 of file Buffer.h.

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

Definition at line 58 of file Buffer.h.

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

Defines the type for specifying service types.

Definition at line 64 of file BaseMessage.h.

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

Definition at line 57 of file Buffer.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

DefaultCapacity

The default capacity used to construct a Message.

Definition at line 83 of file Message.h.

enum ssrc::spread::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

ssrc::spread::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 96 of file Message.h.

Member Function Documentation

void ssrc::spread::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 162 of file Buffer.h.

unsigned int ssrc::spread::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 83 of file Buffer.h.

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

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

Implements ssrc::spread::BaseMessage.

Definition at line 103 of file Message.h.

bool ssrc::spread::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.

void ssrc::spread::BaseMessage::get_membership_info ( MembershipInfo & info ) const [inherited]

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

bool ssrc::spread::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.

unsigned int ssrc::spread::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 ssrc::spread::detail::ByteBuffer::ByteBuffer(), and ssrc::spread::detail::ByteBuffer::operator=().

const_reference ssrc::spread::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 103 of file Buffer.h.

reference ssrc::spread::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 93 of file Buffer.h.

unsigned int ssrc::spread::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.

void ssrc::spread::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 116 of file Buffer.h.

void ssrc::spread::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 135 of file Buffer.h.

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

Same as seek(0).

Definition at line 112 of file ByteBuffer.h.

unsigned int ssrc::spread::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.

const string& ssrc::spread::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.

service_type ssrc::spread::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.

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

Sets the service type to BaseMessage::Agreed.

Definition at line 230 of file BaseMessage.h.

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

Sets the service type to BaseMessage::Causal.

Definition at line 243 of file BaseMessage.h.

void ssrc::spread::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.

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

Sets the service type to BaseMessage::FIFO.

Definition at line 256 of file BaseMessage.h.

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

Sets the service type to BaseMessage::Reliable.

Definition at line 269 of file BaseMessage.h.

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

Sets the service type to BaseMessage::Safe.

Definition at line 295 of file BaseMessage.h.

void ssrc::spread::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.

void ssrc::spread::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.

void ssrc::spread::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.

void ssrc::spread::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.

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

Sets the service type to BaseMessage::Unreliable.

Definition at line 282 of file BaseMessage.h.

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

Returns the number of bytes in the message.

Returns:: The number of bytes in the message.

Implements ssrc::spread::BaseMessage.

Definition at line 99 of file Message.h.

Referenced by ssrc::spread::ScatterMessage::add().

virtual int ssrc::spread::Message::sp_get_membership_info ( Spread::membership_info * info ) const [inline, protected, virtual]

Implements ssrc::spread::BaseMessage.

Definition at line 55 of file Message.h.

virtual int ssrc::spread::Message::sp_get_vs_set_members	(	const Spread::vs_set_info *	vs_set,
		Spread::group_type	member_names[],
		unsigned int	member_names_count
	)			const `[inline, protected, virtual]`

Implements ssrc::spread::BaseMessage.

Definition at line 59 of file Message.h.

virtual int ssrc::spread::Message::sp_get_vs_sets_info	(	Spread::vs_set_info *	vs_sets,
		unsigned int	num_vs_sets,
		unsigned int *	index
	)			const `[inline, protected, virtual]`

Implements ssrc::spread::BaseMessage.

Definition at line 69 of file Message.h.

message_type ssrc::spread::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.

void ssrc::spread::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: