Class Spread::Connection
In: spread.c
Parent: Object


connect   disconnect   io   join   leave   multicast   new   poll   private_group   receive  

Public Class methods

Public Instance methods

Connect to Spread. target specifies which Spread daemon to connect to. It must be a string in the form "port", "port@hostname", or "port@ip".

private_name is the name of this connection. It must be unique among all the connections to a given Spread daemon. If not specified, Spread will assign a randomly-generated unique private name.

all_messages indicates whether this connection should receive all Spread messages, or just data messages. The default is true (so all messages will be received).

If this Spread::Connection instance is presently connected, it will first be silently disconnected.

Disconnect from Spread. Invoking methods like receive and multicast on a disconnected Spread::Connection will throw exceptions. You can reconnect to Spread (perhaps supplying different connection parameters) using connect.

Returns an IO handle representing the connection to Spread. The Spread "mailbox" is actually a file descriptor; I’m not sure if this is documented anywhere, but it seems to be relied upon by a number of things.

Note that it is not safe to do much with the IO object; in particular, reading or writing to it is certainly not wise. This method is intended primarily to allow the use of Kernel#select to wait for Spread activity.

Join the specified group or Array of groups. If an error occurs while attempting to join multiple groups, an exception will immediately be raised, but joins that were processed prior to the error will still take effect.

Leave the specified group or Array of groups. This only makes sense to do if you have previously joined the specified groups via join. However, as of Spread 3.17.3, Spread will not raise an error if you attempt to leave a group you aren’t a member of.

Broadcast message to groups, using the service type service_type. groups is either a String specifying a single group name, or an Array of Strings specifying the list of group names. service_type specifies the desired ordering guarantee for the message (which are available as constants in the Spread module). For more information on the delivery guarantees provided by Spread, see the Spread documentation.

msg_type is the "message type" of the message; this is an arbitrary application-defined value. If not specified, it defaults to 0. The message type of a received data message can be accessed via Spread::DataMessage#msg_type.

If self_discard is true, the message will not be delivered to the sending node. Otherwise, the message will be delivered if the sending node belongs to the group it is sending the message to.

rb_spread imposes no upper limit on message size. By default, Spread itself will reject messages larger than about 144,000 bytes; this limit can be raised by recompiling Spread. If a message is larger than Spread’s maximum message size, Spread::Error::MessageTooLong will be raised.

Returns true if there are any messages waiting to be read, and false otherwise. If poll returns true, receive can be called without blocking.

Returns this connection’s "private group name". This is a group automatically created by Spread that allows private messages to be sent to this connection.

Receive a message from Spread. This method will block indefinitely until a message is available. To avoid blocking, clients can call poll, or use Kernel#select on the IO object returned by io.

The return value is an instance of a subclass of Spread::Message, depending on the type of message that was received.