#include <Mailbox.h>
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.
Mailbox mbox(...); ScatterMessage message; GroupList destination; char *data = "foo";
destination.add("group1");
destination.add("group2");
message.add(data, 3);
mbox.send(message, destination);
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();
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 161 of file 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) 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 throw () |
| Returns the name of the Spread daemon connection. | |
| const string & | name () const throw () |
| Returns the name of the Mailbox. | |
| descriptor_type | descriptor () const throw () |
| Returns the file descriptor of the connection to the Spread daemon. | |
| const string & | private_group () const throw () |
| Returns the private group name of the Mailbox. | |
| bool | group_membership () const throw () |
| Returns true if reception of group membership messages is enabled, false if not. | |
| void | set_drop_receive (const bool drop=true) throw () |
| Sets whether or not received messages that are too large to fit in the provided buffer should be truncated. | |
| bool | drop_receive () const throw () |
| Returns true if excess received data will be dropped, false if not. | |
| void | join (const string &group) throw (Error) |
| Joins the specified group. | |
| void | leave (const string &group) throw (Error) |
| Leaves the specified group. | |
| void | kill () |
| Closes the connection to the Spread daemon without notifying the daemon. | |
| bool | killed () const |
| Returns true if kill() has been called, false if not. | |
| unsigned int | poll () const 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) 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) throw (Error) |
| See send(const ScatterMessage &, const GroupList &). | |
| int | send (const ScatterMessage &message, const GroupList &groups) 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) 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) 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) 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) throw (Error) |
| Same as send(_groups, type, service) where _groups is the internal GroupList. | |
| int | send (const Message &message) throw (Error) |
| Same as send(messaage, _groups) where _groups is the internal GroupList. | |
| int | send (const ScatterMessage &message) throw (Error) |
| Same as send(messaage, _groups) where _groups is the internal GroupList. | |
| int | receive (ScatterMessage &message, GroupList &groups) throw (BufferSizeError, Error) |
| Receives a multicast group message and records the groups the message was sent to. | |
| int | receive (Message &message, GroupList &groups) throw (BufferSizeError, Error) |
| See receive(ScatterMessage &, GroupList &). | |
| int | receive (GroupList &groups) throw (BufferSizeError, Error) |
| Same as receive(_scatter, groups), where _scatter is the internal ScatterMessage. | |
| int | receive (Message &message) throw (BufferSizeError, Error) |
| Same as receive(message, _groups), where _groups is the interal GroupList. | |
| int | receive (ScatterMessage &message) throw (BufferSizeError, Error) |
| Same as receive(message, _groups), where _groups is the interal GroupList. | |
| int | receive () throw (BufferSizeError, Error) |
| Same as receive(_scatter, _groups), where _scatter and _groups are the internal ScatterMessage and GroupList. | |
Static Public Attributes | |
| static const Timeout | ZeroTimeout |
| A constant denoting a timeout of zero seconds and zero microseconds. | |
| typedef Spread::mailbox sava::spread::Mailbox::descriptor_type |
| sava::spread::Mailbox::Mailbox | ( | const string & | connection = "", |
|
| const string & | name = "", |
|||
| const bool | group_membership = true, |
|||
| const Timeout & | timeout = ZeroTimeout, |
|||
| const Priority | priority = Medium | |||
| ) | throw (Error) [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 destoryed, it disconnects. You cannot reuse a Mailbox to establish multiple connections in succession. A new Mailbox must be created for each daemon connection.
| 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. |
| Error | If the connection cannot be established because of a timeout or some other reason. |
Definition at line 54 of file Mailbox.cc.
References sava::spread::Error::AcceptSession, and sava::spread::split_private_group().
| sava::spread::Mailbox::~Mailbox | ( | ) | [inline] |
| const string& sava::spread::Mailbox::connection | ( | ) | const throw () [inline] |
| const string& sava::spread::Mailbox::name | ( | ) | const throw () [inline] |
| descriptor_type sava::spread::Mailbox::descriptor | ( | ) | const throw () [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).
| const string& sava::spread::Mailbox::private_group | ( | ) | const throw () [inline] |
| bool sava::spread::Mailbox::group_membership | ( | ) | const throw () [inline] |
| void sava::spread::Mailbox::set_drop_receive | ( | const bool | drop = true |
) | throw () [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.
| drop | true to drop excess data, false to preserve it and retry. |
| bool sava::spread::Mailbox::drop_receive | ( | ) | const throw () [inline] |
| void sava::spread::Mailbox::join | ( | const string & | group | ) | throw (Error) [inline] |
| void sava::spread::Mailbox::leave | ( | const string & | group | ) | throw (Error) [inline] |
| void sava::spread::Mailbox::kill | ( | ) | [inline] |
Closes the connection to the Spread daemon without notifying the daemon.
If you call this, you can't use the object anymore! It is provided for forking purposes only, so that a child or parent may continue using the Mailbox while the other discontinues using it.
Warning: This method is available only when compiled against Spread 4.x and greater.
| bool sava::spread::Mailbox::killed | ( | ) | const [inline] |
| unsigned int sava::spread::Mailbox::poll | ( | ) | const throw (Error) [inline] |
| bool sava::spread::Mailbox::add_message_part | ( | const void * | data, | |
| const unsigned int | size | |||
| ) | [inline] |
Adds a message part to the internal ScatterMessage.
| data | A pointer to the data buffer. | |
| size | The size of the data buffer in bytes. |
| bool sava::spread::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.
| message | The Message to add. |
| void sava::spread::Mailbox::add_group | ( | const string & | group | ) | [inline] |
| void sava::spread::Mailbox::add_groups | ( | const GroupList & | groups | ) | [inline] |
| string sava::spread::Mailbox::group | ( | const unsigned int | index | ) | const [inline] |
| void sava::spread::Mailbox::copy_groups | ( | GroupList & | groups | ) | [inline] |
| unsigned int sava::spread::Mailbox::count_groups | ( | ) | const [inline] |
Returns the number of groups contained in the internal GroupList.
Definition at line 396 of file Mailbox.h.
References sava::spread::GroupList::size().
| void sava::spread::Mailbox::clear_groups | ( | ) | [inline] |
| unsigned int sava::spread::Mailbox::count_message_parts | ( | ) | const [inline] |
Returns the number of message parts in the internal ScatterMessage.
| void sava::spread::Mailbox::clear_message_parts | ( | ) | [inline] |
Same as send(message, _groups) where _groups is the internal GroupList containing only the supplied group parameter.
Definition at line 121 of file Mailbox.cc.
| int sava::spread::Mailbox::send | ( | const ScatterMessage & | message, | |
| const GroupList & | groups | |||
| ) | throw (Error) |
Multicasts a message to the specified groups using the service and message type of the message.
| message | The message to send. | |
| groups | The list of groups the message should be sent to. |
| Error | If the operation fails. |
Definition at line 89 of file Mailbox.cc.
| int sava::spread::Mailbox::send | ( | const ScatterMessage & | message, | |
| const string & | group | |||
| ) | throw (Error) [inline] |
| int sava::spread::Mailbox::send | ( | const GroupList & | groups, | |
| const BaseMessage::message_type | type = 0, |
|||
| const BaseMessage::service_type | service = BaseMessage::Safe | |||
| ) | throw (Error) [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.
| int sava::spread::Mailbox::send | ( | const string & | group, | |
| const BaseMessage::message_type | type = 0, |
|||
| const BaseMessage::service_type | service = BaseMessage::Safe | |||
| ) | throw (Error) [inline] |
| int sava::spread::Mailbox::send | ( | const BaseMessage::message_type | type = 0, |
|
| const BaseMessage::service_type | service = BaseMessage::Safe | |||
| ) | throw (Error) [inline] |
| int sava::spread::Mailbox::send | ( | const ScatterMessage & | message | ) | throw (Error) [inline] |
| int sava::spread::Mailbox::receive | ( | ScatterMessage & | message, | |
| GroupList & | groups | |||
| ) | throw (BufferSizeError, Error) |
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 iattempt s retried. Also, if drop_receive() is false and the group buffer is too short, the GroupList is automatically resized and the receive attempt retried.
| 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. |
| 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. |
Definition at line 162 of file Mailbox.cc.
References sava::spread::Error::BufferTooShort, sava::spread::BaseMessage::DropReceive, sava::spread::Error::GroupsTooShort, and sava::spread::Message::size().
| int sava::spread::Mailbox::receive | ( | Message & | message, | |
| GroupList & | groups | |||
| ) | throw (BufferSizeError, Error) [inline] |
| int sava::spread::Mailbox::receive | ( | GroupList & | groups | ) | throw (BufferSizeError, Error) [inline] |
Same as receive(_scatter, groups), where _scatter is the internal ScatterMessage.
| int sava::spread::Mailbox::receive | ( | Message & | message | ) | throw (BufferSizeError, Error) [inline] |
| int sava::spread::Mailbox::receive | ( | ScatterMessage & | message | ) | throw (BufferSizeError, Error) [inline] |
| int sava::spread::Mailbox::receive | ( | ) | throw (BufferSizeError, Error) [inline] |
Same as receive(_scatter, _groups), where _scatter and _groups are the internal ScatterMessage and GroupList.
const Timeout sava::spread::Mailbox::ZeroTimeout [static] |