Ruby Spread Interface

DESCRIPTION
-----------
This extension provides a way for ruby to participate in Spread
reliable multicast groups.  Spread is available at
http://www.spread.org/.  Spread is a local/wide area group
communication toolkit that runs on most modern operating systems.  It
allows convenient mechanisms for reliable multicasting information
between applications as well as providing a number of levels of
message assurance.

PREREQUISITES
-------------
This extension requires Spread >= 3.17 daemon and c libraries (with
headers) (see availability info above), and ruby >= 1.3.1.

INSTALLATION
-----------
1. $ ruby extconf.rb
2. $ make
3. # make site-install

THREADING
---------
This version will block all the Threads in Ruby when you call
Spread#receive().  If you don't want to block the other threads, then
do this:

	require 'spread_nonblock'

instead of the usual:

	require 'spread'

This will re-define Spread#receive() to only block the calling thread,
and will also define:

receive_wait()
	wait for data to be readable

receive_blocking()
	this is the original receive() method

EXCEPTIONS
----------
Spread errors will raise a SpreadError exception.  The text of the
error will contain the error number, which can be compared with
SpreadError:: constants (see below).

CLASSES
-------
Spread
SpreadMessage
SpreadError

METHODS
-------
Spread::new(String connect_string, String session_name, [Boolean wants_membership_msgs])
Spread::connect(String connect_string, String session_name, [Boolean wants_membership_msgs])
	These two are aliases of each other. Only call one.
	connect_string is the host and/or port to connect to
	session_name is the private name of this client
	wants_membership_msgs, if true, will make you receive
	membership messages too.

Spread::disconnect
	disconnects session associated with calling object If a Spread
	object gets garbage collected, it will automatically
	disconnect.

Spread::join (String group||Array groups)
	joins one or more groups

Spread::leave (String group||Array groups)
	leaves one or more groups

Spread::multicast (String message, String group||Array groups, Int service_typei [, Integer message_type])
	sends a message to one or more groups

Spread::poll
	returns number of bytes waiting

Spread::receive
	Returns a SpreadMessage object. Will block all the Ruby
	threads (see above).

Spread::mbox
	returns the integer file descriptor of the Spread socket (for
	use with select)

SpreadMessage::message
	returns text of a SpreadMessage object

SpreadMessage::sender
	returns sender of a SpreadMessage object (which is a group for
	membership messages)

SpreadMessage::message_type
	returns the integer application-defined type of the message

SpreadMessage::service_type
	returns the integer service type of the message (whose bits
	you can test with the service types below, or use the is_*
	methods)

SpreadMessage::groups
	returns an Array of group names.

Service type testing
--------------------

SpreadMessage::is_unreliable returns true if service type is UNRELIABLE_MESS
SpreadMessage::is_reliable returns true if service type is RELIABLE_MESS
SpreadMessage::is_fifo returns true if service type is FIFO_MESS
SpreadMessage::is_causal returns true if service type is CAUSAL_MESS
SpreadMessage::is_agreed returns true if service type is AGREED_MESS
SpreadMessage::is_safe returns true if service type is SAFE_MESS
SpreadMessage::is_regular returns true if service type is REGULAR_MESS

SpreadMessage::is_self_discard returns true if service type is SELF_DISCARD
SpreadMessage::is_regular_membership returns true if service type is REG_MEMB_MESS
SpreadMessage::is_transition returns true if service type is TRANSITION_MESS
SpreadMessage::is_caused_by_join returns true if service type is CAUSED_BY_JOIN
SpreadMessage::is_caused_by_leave returns true if service type is CAUSED_BY_LEAVE
SpreadMessage::is_caused_by_disconnect returns true if service type is CAUSED_BY_DISCONNECT
SpreadMessage::is_caused_by_network returns true if service type is CAUSED_BY_NETWORK
SpreadMessage::is_membership returns true if service type is MEMBERSHIP_MESS and not REJECT_MESS
SpreadMessage::is_reject returns true if service type is REJECT_MESS
SpreadMessage::is_self_leave returns true for membership messages caused by your own connection leaving a group

CONSTANTS
---------
--Message Priorities (not used)--
Spread::LOW_PRIORITY
Spread::MEDIUM_PRIORITY
Spread::HIGH_PRIORITY

--Service Types--
Spread::UNRELIABLE_MESS
Spread::RELIABLE_MESS
Spread::FIFO_MESS
Spread::CAUSAL_MESS
Spread::AGREED_MESS
Spread::SAFE_MESS
Spread::REGULAR_MESS

--Extended Service Types --
Spread::SELF_DISCARD
Spread::DROP_RECV
Spread::REG_MEMB_MESS
Spread::TRANSITION_MESS
Spread::CAUSED_BY_JOIN
Spread::CAUSED_BY_LEAVE
Spread::CAUSED_BY_DISCONNECT
Spread::CAUSED_BY_NETWORK
Spread::MEMBERSHIP_MESS
Spread::ENDIAN_RESERVED
Spread::RESERVED

--Spread Errors--

These are numeric constants that will appear in exception strings.
All exception strings due to Spread errors are in the form: "Spread
error (123) ..." where 123 is the actual Spread error code.

SpreadError::ACCEPT_SESSION
SpreadError::ILLEGAL_SPREAD
SpreadError::COULD_NOT_CONNECT
SpreadError::REJECT_QUOTA
SpreadError::REJECT_NO_NAME
SpreadError::REJECT_ILLEGAL_NAME
SpreadError::REJECT_NOT_UNIQUE
SpreadError::REJECT_VERSION
SpreadError::CONNECTION_CLOSED
SpreadError::ILLEGAL_SESSION
SpreadError::ILLEGAL_SERVICE
SpreadError::ILLEGAL_MESSAGE
SpreadError::ILLEGAL_GROUP
SpreadError::BUFFER_TOO_SHORT	# shouldn't see this
SpreadError::GROUPS_TOO_SHORT	# shouldn't see this
