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 }
	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.
Public Member Functions
	ScatterMessage ()
	Creates a ScatterMessage with a size of zero and no message parts.
virtual unsigned int	size () const
	Returns the total size of the message (comprising all of its parts) in bytes.
virtual void	clear ()
	Clears the message for reuse, resetting both its size and number of message parts to zero.
unsigned int	count_message_parts () const
	Returns the number of parts that have been added to the message.
unsigned int	count_message_objects () const
	Returns the number of Message instances that have been added to the message.
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).
bool	add (const Message &message)
	Adds a Message as a message part.
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.
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 50 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 61 of file BaseMessage.h.

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

Defines the type for specifying service types.

Definition at line 64 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 53 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

Definition at line 79 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 137 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 115 of file ScatterMessage.cc.

References MaxScatterElements, and size().

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

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 201 of file ScatterMessage.h.

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

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

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

Implements BaseMessage.

Definition at line 154 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 176 of file ScatterMessage.h.

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 164 of file ScatterMessage.h.

Referenced by Mailbox::count_message_parts().

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

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 ScatterMessage::size ( ) const [inline, virtual]

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 146 of file ScatterMessage.h.

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

Friends And Related Function Documentation

friend class Mailbox [friend]

Definition at line 62 of file ScatterMessage.h.

Member Data Documentation

bool BaseMessage::_endian_mismatch [protected, inherited]

Definition at line 113 of file BaseMessage.h.

Referenced by BaseMessage::endian_mismatch(), and BaseMessage::set_endian_mismatch().

string BaseMessage::_sender [protected, inherited]

Definition at line 114 of file BaseMessage.h.

Referenced by BaseMessage::sender(), and BaseMessage::set_sender().

service_type BaseMessage::_service_type [protected, inherited]

Definition at line 112 of file BaseMessage.h.

Referenced by BaseMessage::service(), BaseMessage::set_self_discard(), and BaseMessage::set_service().

message_type BaseMessage::_type [protected, inherited]

Definition at line 111 of file BaseMessage.h.

Referenced by BaseMessage::set_type(), and 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