ScatterMessage is a reusable container of multiple in-place data buffers. More...

#include <ScatterMessage.h>

Inheritance diagram for ScatterMessage:

Public Types
enum	{ MaxScatterElements = MAX_CLIENT_SCATTER_ELEMENTS }

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, UnreliableSelfDiscard = Unreliable \| SelfDiscard, ReliableSelfDiscard = Reliable \| SelfDiscard, FIFOSelfDiscard = FIFO \| SelfDiscard, CausalSelfDiscard = Causal \| SelfDiscard, AgreedSelfDiscard = Agreed \| SelfDiscard, SafeSelfDiscard = Safe \| SelfDiscard }
	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. More...

typedef Spread::service	service_type
	Defines the type for specifying service types. More...

Public Member Functions
	ScatterMessage ()
	Creates a ScatterMessage with a size of zero and no message parts. More...

virtual unsigned int	size () const
	Returns the total size of the message (comprising all of its parts) in bytes. More...

virtual void	clear ()
	Clears the message for reuse, resetting both its size and number of message parts to zero. More...

unsigned int	count_message_parts () const
	Returns the number of parts that have been added to the message. More...

unsigned int	count_message_objects () const
	Returns the number of Message instances that have been added to the message. More...

bool	add (const void *data, const unsigned int size)
	Adds a message part to the ScatterMessage with a designated number of bytes indicating either the capacity of the buffer (for receiving) or the length of its contents (for sending). More...

bool	add (const Message &message)
	Adds a Message as a message part. More...

void	set_service (const service_type service)
	Sets the service type of the message. More...

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

void	set_type (const message_type type)
	Sets the message type identifier. More...

message_type	type () const
	Returns the type of the message. More...

void	set_sender (const string &sender)
	Sets the message sender. More...

const string &	sender () const
	Returns the message sender. More...

void	set_endian_mismatch (const bool mismatch=true)
	Sets the endian mismatch flag to the specified value. More...

bool	endian_mismatch () const
	Returns true if there is an endian mismatch between sender and receiver, false otherwise. More...

void	set_agreed ()
	Sets the service type to BaseMessage::Agreed. More...

bool	is_agreed () const
	Returns true if service type is BaseMessage::Agreed, false otherwise. More...

void	set_causal ()
	Sets the service type to BaseMessage::Causal. More...

bool	is_causal () const
	Returns true if service type is BaseMessage::Causal, false otherwise. More...

void	set_fifo ()
	Sets the service type to BaseMessage::FIFO. More...

bool	is_fifo () const
	Returns true if service type is BaseMessage::FIFO, false otherwise. More...

void	set_reliable ()
	Sets the service type to BaseMessage::Reliable. More...

bool	is_reliable () const
	Returns true if service type is BaseMessage::Reliable, false otherwise. More...

void	set_unreliable ()
	Sets the service type to BaseMessage::Unreliable. More...

bool	is_unreliable () const
	Returns true if service type is BaseMessage::Unreliable, false otherwise. More...

void	set_safe ()
	Sets the service type to BaseMessage::Safe. More...

bool	is_safe () const
	Returns true if service type is BaseMessage::Safe, false otherwise. More...

void	set_self_discard (const bool discard=true)
	Adds or removes the BaseMessage::SelfDiscard flag to or from the service type. More...

bool	is_self_discard () const
	Returns true if service type has the BaseMessage::SelfDiscard flag set, false otherwise. More...

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

bool	is_membership () const
	Returns true if this is a membership message, false otherwise. More...

Protected Attributes
message_type	_type

service_type	_service_type

bool	_endian_mismatch

string	_sender

Friends
class	Mailbox

Detailed Description

ScatterMessage is a reusable container of multiple in-place data buffers.

It can be populated with Message instances or straight data pointers. However, the auto-resizing feature of Mailbox::receive will be exercised only if the ScatterMessage contains at least one Message instance. You will want to use a ScatterMessage primarily when you want to avoid multiple buffer copies. For example, if you know the format of an incoming message you can add data pointers for each message part instead of parsing the message and copying the data. Also, instead of allocating a message buffer and copying multiple data items to it for a send, you can populate a ScatterMessage with pointers to the data items and avoid an extra copy.

We do not document ScatterMessage protected members because they are intended only for internal library use.

Definition at line 48 of file ScatterMessage.h.

Member Typedef Documentation

typedef Spread::int16 BaseMessage::message_type

inherited

Defines the type for 16-bit message type identifiers.

Definition at line 63 of file BaseMessage.h.

typedef Spread::service BaseMessage::service_type

inherited

Defines the type for specifying service types.

Definition at line 66 of file BaseMessage.h.

Member Enumeration Documentation

anonymous enum

Enumerator
MaxScatterElements	The maximum number of elements that can be added to a scatter message.

Definition at line 51 of file ScatterMessage.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
UnreliableSelfDiscard
ReliableSelfDiscard
FIFOSelfDiscard
CausalSelfDiscard
AgreedSelfDiscard
SafeSelfDiscard

Definition at line 81 of file BaseMessage.h.

Constructor & Destructor Documentation

ScatterMessage::ScatterMessage ( )

inline

Creates a ScatterMessage with a size of zero and no message parts.

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

Definition at line 133 of file ScatterMessage.h.

Member Function Documentation

bool ScatterMessage::add	(	const void *	data,
		const unsigned int	size
	)

Adds a message part to the ScatterMessage with a designated number of bytes indicating either the capacity of the buffer (for receiving) or the length of its contents (for sending).

Parameters

data	A pointer to the data buffer to add.
size	The number of bytes to be filled in to or read from the data buffer.

Returns: true if the message part was added, false if there's no more parts can be added.

Definition at line 116 of file ScatterMessage.cc.

References __END_NS_SSRC_SPREAD, MaxScatterElements, and size().

Referenced by add(), Mailbox::add_message_part(), and count_message_objects().

bool ScatterMessage::add ( const Message & message )

inline

Adds a Message as a message part.

ScatterMessage will store a pointer to the original Message; therefore you should not alter the Message between the time it is added and when the send or receive is performed. Note that for receives, each Message added will be filled up to its capacity, not its size. The size will be ajdusted to reflect the amount of data written to the Message. The capacity will not be increased to accommodate more data except for the last Message added to the ScatterMessage. If you don't want this behavior, use add(const void *, const unsigned int) instead, with &message[0] as the data argument. When using fixed-length message parts, it is often useful to tack on a Message as the last message part to store any unexpected overflow.

Parameters

message The Message to add.

Returns: true if the message part was added, false if no more parts can be added.

Definition at line 197 of file ScatterMessage.h.

References __END_NS_SSRC_SPREAD, add(), and Message::size().

virtual void ScatterMessage::clear ( )

inlinevirtual

Clears the message for reuse, resetting both its size and number of message parts to zero.

Implements BaseMessage.

Definition at line 150 of file ScatterMessage.h.

Referenced by Mailbox::clear_message_parts().

unsigned int ScatterMessage::count_message_objects ( ) const

inline

Returns the number of Message instances that have been added to the message.

This number will be different from that returned by count_message_parts() if any straight pointers have ben added.

Returns: The number of Message instances that have been added to the message.

Definition at line 172 of file ScatterMessage.h.

References add().

Referenced by if().

unsigned int ScatterMessage::count_message_parts ( ) const

inline

Returns the number of parts that have been added to the message.

Returns: The number of parts that have been added to the message.

Definition at line 160 of file ScatterMessage.h.

Referenced by Mailbox::count_message_parts().

bool BaseMessage::endian_mismatch ( ) const

inlineinherited

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 227 of file BaseMessage.h.

References BaseMessage::_endian_mismatch.

bool BaseMessage::is_agreed ( ) const

inlineinherited

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

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

Definition at line 240 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_causal ( ) const

inlineinherited

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

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

Definition at line 253 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_fifo ( ) const

inlineinherited

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

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

Definition at line 266 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_membership ( ) const

inlineinherited

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

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

Definition at line 345 of file BaseMessage.h.

References __END_NS_SSRC_SPREAD, and BaseMessage::service().

bool BaseMessage::is_regular ( ) const

inlineinherited

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 337 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_reliable ( ) const

inlineinherited

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

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

Definition at line 279 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_safe ( ) const

inlineinherited

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

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

Definition at line 305 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_self_discard ( ) const

inlineinherited

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 328 of file BaseMessage.h.

References BaseMessage::service().

bool BaseMessage::is_unreliable ( ) const

inlineinherited

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

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

Definition at line 292 of file BaseMessage.h.

References BaseMessage::service().

const string& BaseMessage::sender ( ) const

inlineinherited

Returns the message sender.

This only has meaning for received messages.

Returns: The message sender.

Definition at line 209 of file BaseMessage.h.

References BaseMessage::_sender.

Referenced by BaseMessage::set_sender().

service_type BaseMessage::service ( ) const

inlineinherited

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

inlineinherited

Sets the service type to BaseMessage::Agreed.

Definition at line 232 of file BaseMessage.h.

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

void BaseMessage::set_causal ( )

inlineinherited

Sets the service type to BaseMessage::Causal.

Definition at line 245 of file BaseMessage.h.

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

void BaseMessage::set_endian_mismatch ( const bool mismatch = true )

inlineinherited

Sets the endian mismatch flag to the specified value.

Parameters

mismatch The mismatch value.

Definition at line 217 of file BaseMessage.h.

Referenced by if().

void BaseMessage::set_fifo ( )

inlineinherited

Sets the service type to BaseMessage::FIFO.

Definition at line 258 of file BaseMessage.h.

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

void BaseMessage::set_reliable ( )

inlineinherited

Sets the service type to BaseMessage::Reliable.

Definition at line 271 of file BaseMessage.h.

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

void BaseMessage::set_safe ( )

inlineinherited

Sets the service type to BaseMessage::Safe.

Definition at line 297 of file BaseMessage.h.

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

void BaseMessage::set_self_discard ( const bool discard = true )

inlineinherited

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 316 of file BaseMessage.h.

References BaseMessage::SelfDiscard.

void BaseMessage::set_sender ( const string & sender )

inlineinherited

Sets the message sender.

Parameters

sender The message sender.

Definition at line 201 of file BaseMessage.h.

References BaseMessage::sender().

Referenced by if().

void BaseMessage::set_service ( const service_type service )

inlineinherited

Sets the service type of the message.

Parameters

service The service type of the message.

Definition at line 167 of file BaseMessage.h.

References BaseMessage::service().

Referenced by if(), 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 )

inlineinherited

Sets the message type identifier.

Parameters

type	The new message type.

Definition at line 185 of file BaseMessage.h.

References BaseMessage::type().

Referenced by if(), and Mailbox::send().

void BaseMessage::set_unreliable ( )

inlineinherited

Sets the service type to BaseMessage::Unreliable.

Definition at line 284 of file BaseMessage.h.

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

virtual unsigned int ScatterMessage::size ( ) const

inlinevirtual

Returns the total size of the message (comprising all of its parts) in bytes.

Returns: The total size of the message in bytes.

Implements BaseMessage.

Definition at line 142 of file ScatterMessage.h.

Referenced by add(), and if().

message_type BaseMessage::type ( ) const

inlineinherited

Returns the type of the message.

Returns: The type of the message.

Definition at line 193 of file BaseMessage.h.

References BaseMessage::_type.

Referenced by BaseMessage::set_type().

Friends And Related Function Documentation

friend class Mailbox

friend

Definition at line 60 of file ScatterMessage.h.

Member Data Documentation

bool BaseMessage::_endian_mismatch

protectedinherited

Definition at line 115 of file BaseMessage.h.

Referenced by BaseMessage::endian_mismatch().

string BaseMessage::_sender

protectedinherited

Definition at line 116 of file BaseMessage.h.

Referenced by BaseMessage::sender().

service_type BaseMessage::_service_type

protectedinherited

Definition at line 114 of file BaseMessage.h.

Referenced by BaseMessage::service().

message_type BaseMessage::_type

protectedinherited

Definition at line 113 of file BaseMessage.h.

Referenced by BaseMessage::type().

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

Public Types

Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation