The Mailbox class wraps the file descriptor returned after establishing a connection to a Spread daemon and the operations that can be performed with it. More...

#include <Mailbox.h>

Public Types
enum	Priority { Low = LOW_PRIORITY, Medium = MEDIUM_PRIORITY, High = HIGH_PRIORITY }
	The Priority enumeration defines the priority levels for establishing a mailbox connection. More...
typedef Spread::mailbox	descriptor_type
	Defines the type for the Mailbox file descriptor.
Public Member Functions
	Mailbox (const string &connection="", const string &name="", const bool group_membership=true, const Timeout &timeout=ZeroTimeout, const Priority priority=Medium) SSRC_DECL_THROW(Error)
	Creates a Mailbox configured with the specified parameters.
	~Mailbox ()
	Disconnects from the Spread daemon unless kill() was called during the lifetime of the object.
const string &	connection () const
	Returns the name of the Spread daemon connection.
const string &	name () const
	Returns the name of the Mailbox.
descriptor_type	descriptor () const
	Returns the file descriptor of the connection to the Spread daemon.
const string &	private_group () const
	Returns the private group name of the Mailbox.
bool	group_membership () const
	Returns true if reception of group membership messages is enabled, false if not.
void	set_drop_receive (const bool drop=true)
	Sets whether or not received messages that are too large to fit in the provided buffer should be truncated.
bool	drop_receive () const
	Returns true if excess received data will be dropped, false if not.
void	join (const string &group) SSRC_DECL_THROW(Error)
	Joins the specified group.
void	leave (const string &group) SSRC_DECL_THROW(Error)
	Leaves the specified group.
bool	killed () const
	Returns true if kill() has been called, false if not.
unsigned int	poll () const SSRC_DECL_THROW(Error)
	Polls the Mailbox to see if any messags have arrived that can be retrieved via receive().
bool	add_message_part (const void *data, const unsigned int size)
	Adds a message part to the internal ScatterMessage.
bool	add_message_part (const Message &message)
	Adds a Message to the internal ScatterMessage.
void	add_group (const string &group)
	Appends a group name to the end of the internal GroupList.
void	add_groups (const GroupList &groups)
	Appends the contents of a GroupList to the end of the internal GroupList.
string	group (const unsigned int index) const
	Returns the name of the group at the specified position in the internal Grouplist.
void	copy_groups (GroupList &groups)
	Copies the internal GroupList.
unsigned int	count_groups () const
	Returns the number of groups contained in the internal GroupList.
void	clear_groups ()
	Clears the internal GroupList.
unsigned int	count_message_parts () const
	Returns the number of message parts in the internal ScatterMessage.
void	clear_message_parts ()
	Clears the internal ScatterMessage.
int	send (const Message &message, const string &group) SSRC_DECL_THROW(Error)
	Same as send(message, _groups) where _groups is the internal GroupList containing only the supplied group parameter.
int	send (const Message &message, const GroupList &groups) SSRC_DECL_THROW(Error)
	See send(const ScatterMessage &, const GroupList &).
int	send (const ScatterMessage &message, const GroupList &groups) SSRC_DECL_THROW(Error)
	Multicasts a message to the specified groups using the service and message type of the message.
int	send (const ScatterMessage &message, const string &group) SSRC_DECL_THROW(Error)
	Same as send(message, _groups) where _groups is the internal GroupList containing only the supplied group parameter.
int	send (const GroupList &groups, const BaseMessage::message_type type=0, const BaseMessage::service_type service=BaseMessage::Safe) SSRC_DECL_THROW(Error)
	Same as send(_scatter, groups) where _scatter is the internal ScatterMessage after having its type and service set to to the supplied type and service values.
int	send (const string &group, const BaseMessage::message_type type=0, const BaseMessage::service_type service=BaseMessage::Safe) SSRC_DECL_THROW(Error)
	Same as send(_groups, type, service) where _groups is the internal GroupList containing only the supplied group parameter.
int	send (const BaseMessage::message_type type=0, const BaseMessage::service_type service=BaseMessage::Safe) SSRC_DECL_THROW(Error)
	Same as send(_groups, type, service) where _groups is the internal GroupList.
int	send (const Message &message) SSRC_DECL_THROW(Error)
	Same as send(messaage, _groups) where _groups is the internal GroupList.
int	send (const ScatterMessage &message) SSRC_DECL_THROW(Error)
	Same as send(messaage, _groups) where _groups is the internal GroupList.
int	receive (ScatterMessage &message, GroupList &groups) SSRC_DECL_THROW(BufferSizeError
	Receives a multicast group message and records the groups the message was sent to.
int	receive (Message &message, GroupList &groups) SSRC_DECL_THROW(BufferSizeError
	See receive(ScatterMessage &, GroupList &).
Public Attributes
int	Error
Static Public Attributes
static const Timeout	ZeroTimeout
	A constant denoting a timeout of zero seconds and zero microseconds.

Detailed Description

The Mailbox class wraps the file descriptor returned after establishing a connection to a Spread daemon and the operations that can be performed with it.

The class is not named Connection because it can lead to confusion. The connection is between the client application and the Spread daemon, but through that connection the client application can send and receive messages to and from multiple destinations. We feel that Mailbox is the more conceptually appropriate metaphor. Messages can be sent and received to and from multiple destinations through a mailbox. The Spread daemon acts as a post office, mediating and routing the message transmission and retrieval. A connection is a point-to-point concept. Beyond initializing a Mailbox, the client application need not be conscious that there is a Spread daemon in the communication path.

A Mailbox provides three different modes of interaction for sending and receivng messages. The first mode requires you to provide the message and destination/source group list on every send and receive. The second mode involves using only the internal ScatterMessage and GroupList maintained by Mailbox. That is, you add groups and messages to Mailbox instead of your own GroupList and ScatterMessage. The third mode involves a mixture of the two, where you can specify either your own message or group list, and let the Mailbox internal message or group list provide the other.

The second and third modes are intended as convenience methods for those programmers who prefer that model. The first mode is a direct analog to the Spread C API and is what was originally intended as the primary mode of use. However, it turns out that the Spread C API delegates all of the non-scatter send and receive functions to the scatter send and receive functions. Therefore, Mailbox uses only the scatter versions of the functions to do its work, bypassing a level of indirection. However, to support sending a single message to a single group, as in send(const Message &, const string &), Mailbox must maintain its own GroupList and place the group name in the GroupList. Also, it must maintain its own ScatterMessage and add the Message to the ScatterMessage before the send. In fact, this is what the non-scatter Spread C API functions do. Since these scratch variables are maintained anyway to support the non-scatter convenience methods, we don't lose anything by making them availble in the public API. It is up to the programmer to choose between the methods. To disambiguate, whenever you provide your own ScatterMessage or GroupList, it is used directly, bypassing the internal scratch variables. The scratch variables are used only when you provide single-group string destination or non-scatter messages.

Examples

Mode 1 (provide your own Message and GroupList)

 Mailbox mbox(...);
 ScatterMessage message;
 GroupList destination;
 char *data = "foo";

 destination.add("group1");
 destination.add("group2");
 message.add(data, 3);
 mbox.send(message, destination);

Mode 2 (use Mailbox buffers)

 Mailbox mbox(...);
 char *data = "foo";

 mbox.clear_groups();
 mbox.add_group("group1");
 mbox.add_group("group2");
 mbox.clear_message_parts();
 mbox.add_message_part(data, 3);
 mbox.send();

Mode 3 (mixed mode)

 Mailbox mbox(...);
 ScatterMessage message;
 char *data = "foo";

 mbox.clear_groups();
 mbox.add_group("group1");
 mbox.add_group("group2");
 message.add(data, 3);
 mbox.send(message);

Definition at line 160 of file Mailbox.h.

Member Typedef Documentation

typedef Spread::mailbox Mailbox::descriptor_type

Defines the type for the Mailbox file descriptor.

Definition at line 163 of file Mailbox.h.

Member Enumeration Documentation

enum Mailbox::Priority

The Priority enumeration defines the priority levels for establishing a mailbox connection.

Enumerator:

Low
Medium
High

Definition at line 171 of file Mailbox.h.

Constructor & Destructor Documentation

Mailbox::Mailbox	(	const string &	connection = `""`,
		const string &	name = `""`,
		const bool	group_membership = `true`,
		const Timeout &	timeout = `ZeroTimeout`,
		const Priority	priority = `Medium`
	)		`[explicit]`

Creates a Mailbox configured with the specified parameters.

Mailbox follows the "resource acquisition is initialization" model. When a Mailbox is created, it establishes a connection with the specified Spread daemon. When it is destroyed, it disconnects. You cannot reuse a Mailbox to establish multiple connections in succession. A new Mailbox must be created for each daemon connection.

Mailbox::Mailbox sets the FD_CLOEXEC flag on the connection's file descriptor.

Parameters:

connection	The name of the Spread daemon to connect to. A zero-length string indicates that the default daemon should be connected to ("4803" or "4803@localhost"; this is an undocumented feature of SP_connect).
name	The name of the session (used to create the private group name). A zero-length string value indicates that the Spread daemon should assign the session a random unique name.
group_membership	true if you want to receive group membership messages, false if not. The default is true.
timeout	A timeout for connecting to the daemon. A value of zero designates no timeout (the default).
priority	The priority level for establishing the connection.

Exceptions:

Error If the connection cannot be established because of a timeout or some other reason.

Definition at line 57 of file Mailbox.cc.

References Error::AcceptSession, and split_private_group().

Mailbox::~Mailbox ( ) [inline]

Disconnects from the Spread daemon unless kill() was called during the lifetime of the object.

Definition at line 193 of file Mailbox.h.

References killed().

Member Function Documentation

void Mailbox::add_group ( const string & group ) [inline]

Appends a group name to the end of the internal GroupList.

Parameters:

group The name of the group to add.

Definition at line 357 of file Mailbox.h.

References GroupList::add().

Referenced by send().

void Mailbox::add_groups ( const GroupList & groups ) [inline]

Appends the contents of a GroupList to the end of the internal GroupList.

Parameters:

groups The GroupList to append.

Definition at line 366 of file Mailbox.h.

References GroupList::add().

bool Mailbox::add_message_part	(	const void *	data,
		const unsigned int	size
	)		`[inline]`

Adds a message part to the internal ScatterMessage.

Parameters:

data	A pointer to the data buffer.
size	The size of the data buffer in bytes.

Definition at line 335 of file Mailbox.h.

References ScatterMessage::add().

bool Mailbox::add_message_part ( const Message & message ) [inline]

Adds a Message to the internal ScatterMessage.

The service type and message type of the Message will not be used in a send because the internal ScatterMessage may contain multiple Message parts. You must specify the types as parameters to the appropriate send() call.

Parameters:

message The Message to add.

Definition at line 348 of file Mailbox.h.

References ScatterMessage::add().

void Mailbox::clear_groups ( ) [inline]

Clears the internal GroupList.

Definition at line 402 of file Mailbox.h.

References GroupList::clear().

Referenced by send().

void Mailbox::clear_message_parts ( ) [inline]

Clears the internal ScatterMessage.

Definition at line 417 of file Mailbox.h.

References ScatterMessage::clear().

const string& Mailbox::connection ( ) const [inline]

Returns the name of the Spread daemon connection.

Returns:: The name of the Spread daemon connection.

Definition at line 202 of file Mailbox.h.

void Mailbox::copy_groups ( GroupList & groups ) [inline]

Copies the internal GroupList.

Parameters:

groups A reference to the GroupList that will store the copy.

Definition at line 387 of file Mailbox.h.

unsigned int Mailbox::count_groups ( ) const [inline]

Returns the number of groups contained in the internal GroupList.

Returns:: The number of groups contained in the internal GroupList.

Definition at line 395 of file Mailbox.h.

References GroupList::size().

unsigned int Mailbox::count_message_parts ( ) const [inline]

Returns the number of message parts in the internal ScatterMessage.

Returns:: The number of message parts in the internal ScatterMessage.

Definition at line 410 of file Mailbox.h.

References ScatterMessage::count_message_parts().

descriptor_type Mailbox::descriptor ( ) const [inline]

Returns the file descriptor of the connection to the Spread daemon.

This file descriptor is made available to allow you to hook into an event handling system (e.g., select, poll, Linux epoll).

Returns:: The file descriptor of the connection to the Spread daemon.

Definition at line 220 of file Mailbox.h.

bool Mailbox::drop_receive ( ) const [inline]

Returns true if excess received data will be dropped, false if not.

Returns:: true if excess received data will be dropped, false if not.

Definition at line 257 of file Mailbox.h.

string Mailbox::group ( const unsigned int index ) const [inline]

Returns the name of the group at the specified position in the internal Grouplist.

Parameters:

index The index of the group name to return.

Returns:: The name of the group at the specified position in the internal Grouplist.

Definition at line 378 of file Mailbox.h.

Referenced by join(), leave(), and send().

bool Mailbox::group_membership ( ) const [inline]

Returns true if reception of group membership messages is enabled, false if not.

Returns:: true if reception of group membership messages is enabled, false if not.

Definition at line 238 of file Mailbox.h.

void Mailbox::join ( const string & group ) [inline]

Joins the specified group.

Parameters:

group The name of the group to join.

Exceptions:

Error If the operation fails.

Definition at line 267 of file Mailbox.h.

References Error, and group().

bool Mailbox::killed ( ) const [inline]

Returns true if kill() has been called, false if not.

Warning: This method always returns false when not compiled against Spread 4.x and greater.

Returns:: true if kill() has been called, false if not.

Definition at line 310 of file Mailbox.h.

Referenced by ~Mailbox().

void Mailbox::leave ( const string & group ) [inline]

Leaves the specified group.

Parameters:

group The name of the group to leave.

Exceptions:

Error If the operation fails.

Definition at line 279 of file Mailbox.h.

References Error, and group().

const string& Mailbox::name ( ) const [inline]

Returns the name of the Mailbox.

Returns:: The name of the Mailbox.

Definition at line 210 of file Mailbox.h.

unsigned int Mailbox::poll ( ) const [inline]

Polls the Mailbox to see if any messags have arrived that can be retrieved via receive().

Returns:: The number of bytes available to be received (0 if there are no messages).

Exceptions:

Error If the operation fails.

Definition at line 322 of file Mailbox.h.

References Error.

const string& Mailbox::private_group ( ) const [inline]

Returns the private group name of the Mailbox.

Returns:: The private group name of the Mailbox.

Definition at line 228 of file Mailbox.h.

int Mailbox::receive	(	ScatterMessage &	message,
		GroupList &	groups
	)

Receives a multicast group message and records the groups the message was sent to.

If drop_receive() is false and the message buffers are too short, the last Message instance in the ScatterMessage is resized to hold any excess data (see ScatterMessage::add(const Message &) for additional discussion) and the receive attempt is retried. Also, if drop_receive() is false and the group buffer is too short, the GroupList is automatically resized and the receive attempt retried.

Parameters:

message	A reference to the message that will store the received data.
groups	A reference to the Grouplist that will store the groups the message was sent to.

Returns:: The total numbr of bytes received. If drop_receive() is true, either Error::BufferTooShort or Error::GroupsTooShort is returned when data is dropped.

Exceptions:

BufferSizeError If the Spread C API does not provide enough information to retry a receive (when drop_receive() is false). This should not happen unless there is a bug in the Spread API. Also, a BufferSizeError is thrown when no Message instances are provided in the ScatterMessage and there is a Error::BufferTooShort error. In that case, it is impossible for receive to resize the message and retry. In such a case, you will have to manuallly resize your buffers and retry based on the information provided by the :BufferSizeError.

Error If the operation fails.

int Mailbox::receive	(	Message &	message,
		GroupList &	groups
	)

See receive(ScatterMessage &, GroupList &).

Exceptions:

BufferSizeError
Error

int Mailbox::send	(	const Message &	message,
		const GroupList &	groups
	)

See send(const ScatterMessage &, const GroupList &).

Definition at line 112 of file Mailbox.cc.

int Mailbox::send	(	const BaseMessage::message_type	type = `0`,
		const BaseMessage::service_type	service = `BaseMessage::Safe`
	)		`[inline]`

Same as send(_groups, type, service) where _groups is the internal GroupList.

Exceptions:

Error If the operation fails.

Definition at line 479 of file Mailbox.h.

References send().

int Mailbox::send	(	const ScatterMessage &	message,
		const string &	group
	)		`[inline]`

Same as send(message, _groups) where _groups is the internal GroupList containing only the supplied group parameter.

Definition at line 434 of file Mailbox.h.

References add_group(), clear_groups(), group(), and send().

int Mailbox::send	(	const Message &	message,
		const string &	group
	)

Same as send(message, _groups) where _groups is the internal GroupList containing only the supplied group parameter.

Definition at line 126 of file Mailbox.cc.

Referenced by send().

int Mailbox::send ( const ScatterMessage & message ) [inline]

Same as send(messaage, _groups) where _groups is the internal GroupList.

Exceptions:

Error If the operation fails.

Definition at line 500 of file Mailbox.h.

References send().

int Mailbox::send	(	const string &	group,
		const BaseMessage::message_type	type = `0`,
		const BaseMessage::service_type	service = `BaseMessage::Safe`
	)		`[inline]`

Same as send(_groups, type, service) where _groups is the internal GroupList containing only the supplied group parameter.

Exceptions:

Error If the operation fails.

Definition at line 464 of file Mailbox.h.

References add_group(), clear_groups(), and send().

int Mailbox::send ( const Message & message ) [inline]

Same as send(messaage, _groups) where _groups is the internal GroupList.

Exceptions:

Error If the operation fails.

Definition at line 491 of file Mailbox.h.

References send().

int Mailbox::send	(	const GroupList &	groups,
		const BaseMessage::message_type	type = `0`,
		const BaseMessage::service_type	service = `BaseMessage::Safe`
	)		`[inline]`

Same as send(_scatter, groups) where _scatter is the internal ScatterMessage after having its type and service set to to the supplied type and service values.

Exceptions:

Error If the operation fails.

Definition at line 449 of file Mailbox.h.

References send(), BaseMessage::set_service(), and BaseMessage::set_type().

int Mailbox::send	(	const ScatterMessage &	message,
		const GroupList &	groups
	)

Multicasts a message to the specified groups using the service and message type of the message.

Parameters:

message	The message to send.
groups	The list of groups the message should be sent to.

Returns:: The number of bytes sent.

Exceptions:

Error If the operation fails.

Definition at line 94 of file Mailbox.cc.

void Mailbox::set_drop_receive ( const bool drop = true ) [inline]

Sets whether or not received messages that are too large to fit in the provided buffer should be truncated.

By default, Mailbox does not drop data and instead resizes Message instances to hold the data and retries the receive.

Parameters:

drop	true to drop excess data, false to preserve it and retry.

Definition at line 249 of file Mailbox.h.

Member Data Documentation

int Mailbox::Error

Definition at line 505 of file Mailbox.h.

Referenced by join(), leave(), and poll().

NS_SSRCSPREAD_DECL_PREFIX const Timeout Mailbox::ZeroTimeout [static]

A constant denoting a timeout of zero seconds and zero microseconds.

This value is taken to mean block indefinitely.

Definition at line 165 of file Mailbox.h.

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

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Examples

Mode 1 (provide your own Message and GroupList)

Mode 2 (use Mailbox buffers)

Mode 3 (mixed mode)

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation