|
|
| |
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. More...
|
| |
| |
~Mailbox () |
| |
Disconnects from the Spread daemon unless kill() was called during the lifetime of the object. More...
|
| |
| const string & |
connection () const |
| |
Returns the name of the Spread daemon connection. More...
|
| |
| const string & |
name () const |
| |
Returns the name of the Mailbox. More...
|
| |
| descriptor_type |
descriptor () const |
| |
Returns the file descriptor of the connection to the Spread daemon. More...
|
| |
| const string & |
private_group () const |
| |
Returns the private group name of the Mailbox. More...
|
| |
| bool |
group_membership () const |
| |
Returns true if reception of group membership messages is enabled, false if not. More...
|
| |
| 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. More...
|
| |
| bool |
drop_receive () const |
| |
Returns true if excess received data will be dropped, false if not. More...
|
| |
| void |
join (const string &group) SSRC_DECL_THROW(Error) |
| |
Joins the specified group. More...
|
| |
| void |
leave (const string &group) SSRC_DECL_THROW(Error) |
| |
Leaves the specified group. More...
|
| |
| bool |
killed () const |
| |
Returns true if kill() has been called, false if not. More...
|
| |
| unsigned int |
poll () const SSRC_DECL_THROW(Error) |
| |
Polls the Mailbox to see if any messags have arrived that can be retrieved via receive(). More...
|
| |
| bool |
add_message_part (const void *data, const unsigned int size) |
| |
Adds a message part to the internal ScatterMessage. More...
|
| |
| bool |
add_message_part (const Message &message) |
| |
Adds a Message to the internal ScatterMessage. More...
|
| |
| void |
add_group (const string &group) |
| |
Appends a group name to the end of the internal GroupList. More...
|
| |
| void |
add_groups (const GroupList &groups) |
| |
Appends the contents of a GroupList to the end of the internal GroupList. More...
|
| |
| string |
group (const unsigned int index) const |
| |
Returns the name of the group at the specified position in the internal Grouplist. More...
|
| |
| void |
copy_groups (GroupList &groups) |
| |
Copies the internal GroupList. More...
|
| |
| unsigned int |
count_groups () const |
| |
Returns the number of groups contained in the internal GroupList. More...
|
| |
| void |
clear_groups () |
| |
Clears the internal GroupList. More...
|
| |
| unsigned int |
count_message_parts () const |
| |
Returns the number of message parts in the internal ScatterMessage. More...
|
| |
| void |
clear_message_parts () |
| |
Clears the internal ScatterMessage. More...
|
| |
| 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. More...
|
| |
| int |
send (const Message &message, const GroupList &groups) SSRC_DECL_THROW(Error) |
| |
See send(const ScatterMessage &, const GroupList &). More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| 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. More...
|
| |
| int |
send (const Message &message) SSRC_DECL_THROW(Error) |
| |
Same as send(messaage, _groups) where _groups is the internal GroupList. More...
|
| |
| int |
send (const ScatterMessage &message) SSRC_DECL_THROW(Error) |
| |
Same as send(messaage, _groups) where _groups is the internal GroupList. More...
|
| |
| int |
receive (ScatterMessage &message, GroupList &groups) SSRC_DECL_THROW(BufferSizeError |
| |
Receives a multicast group message and records the groups the message was sent to. More...
|
| |
| int |
receive (Message &message, GroupList &groups) SSRC_DECL_THROW(BufferSizeError |
| |
See receive(ScatterMessage &, GroupList &). More...
|
| |
| |
add_message_part (message) |
| |
| return |
receive (_scatter, groups) |
| |
| int |
receive (GroupList &groups) SSRC_DECL_THROW(BufferSizeError |
| |
Same as receive(_scatter, groups), where _scatter is the internal ScatterMessage. More...
|
| |
| int |
receive (Message &message) SSRC_DECL_THROW(BufferSizeError |
| |
Same as receive(message, _groups), where _groups is the interal GroupList. More...
|
| |
| int |
receive (ScatterMessage &message) SSRC_DECL_THROW(BufferSizeError |
| |
Same as receive(message, _groups), where _groups is the interal GroupList. More...
|
| |
| int |
receive () SSRC_DECL_THROW(BufferSizeError |
| |
Same as receive(_scatter, _groups), where _scatter and _groups are the internal ScatterMessage and GroupList. More...
|
| |
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 158 of file Mailbox.h.
