Spread wrapper for Python
=========================

The spread module is an intentionally thin layer on top of the Spread
client library.  It defines functions, exceptions, types and
constants.  For additional documentation, see the Spread man pages,
especially SP_connect, SP_disconnect, SP_join, SP_leave, SP_multicast,
SP_receive, and SP_poll.  The Spread website (www.spread.org) gives
additional information; especially the Spread Users Guide available
there is helpful.


Functions
---------

connect([spread_name[, private_name[, priority[, membership]]]]) -
Connect to the Spread daemon and return an object of type MailboxType.
Upon failure, SpreadError is raised.  See the SP_connect() man page
for more information.  Arguments: spread_name is a string specifying
the port and host of the spread daemon to use, of the form
"<port>@<hostname>" or "<port>", where <port> is an integer port
number (typically the constant DEFAULT_SPREAD_PORT) represented as a
string, and <hostname> specifies the host where the daemon runs,
typically "localhost".  private_name is a string specifying the name
under which this client is to be known.  priority is 0 or 1, currently
unused.  membership should be 1 to receive membership messages, and 0
to decline receiving those.  All arguments are optional; defaults are
the default Spread port and host, a private name made up by Spread, 0,
and 1, respectively.


Exceptions
----------

SpreadError - The exception raised for Spread-related errors.  The
arguments are usually a tuple of an int and a string, indicating the
error constant and the corresponding error message.  Sometimes the
argument is just a string indicating some higher-level error
condition.


Types
-----

MailboxType - This object represents a connection to a spread daemon.
Different mailboxes are completely independent.  Methods are described
below.  Instance variables: private_group is the private group name
assigned to this connection by the spread daemon (see the SP_connect
man page).

RegularMsgType - This object represents a data message as returned by
the receive() method.  There are no methods.  Instance variables:
msg_type: an int giving the message type (a mask of various constants
defined below, see the SP_receive man page); endian: an int that is
zero if there are no endian issues with the message; sender: the
private name of the connection that sent the message; groups: a list
of the group names to which the message was multicast (only groups are
listed of which the receiving connection is a member); message: a
string giving the data associated with the message.

MembershipMsgType - This object represents a membership message as
returned by the receive() method.  There are no methods.  Instance
variables: reason: the message type, which is exactly one of the
constants defined below CAUSED_BY_JOIN, CAUSED_BY_LEAVE,
CAUSED_BY_DISCONNECT, or CAUSED_BY_NETWORK, or zero if this is a
transitional membership message; group: the group to which this
message pertains; group_id: the unique identifier assigned to this
group (not a string but an opaque object); members: a list of private
names giving the new set of members of the group; extra: a list of
private names of members that have joined or left the group (which it
is depends on the reason instance variable).  Note: for transitional
messages (indicated by a reason of zero), the members and extra lists
are both empty.


Constants
---------

Constants defined by Spread:

LOW_PRIORITY MEDIUM_PRIORITY HIGH_PRIORITY DEFAULT_SPREAD_PORT
SPREAD_VERSION MAX_GROUP_NAME MAX_PRIVATE_NAME MAX_PROC_NAME
UNRELIABLE_MESS RELIABLE_MESS FIFO_MESS CAUSAL_MESS AGREED_MESS
SAFE_MESS REGULAR_MESS SELF_DISCARD DROP_RECV REG_MEMB_MESS
TRANSITION_MESS CAUSED_BY_JOIN CAUSED_BY_LEAVE CAUSED_BY_DISCONNECT
CAUSED_BY_NETWORK MEMBERSHIP_MESS ENDIAN_RESERVED RESERVED REJECT_MESS
ACCEPT_SESSION

Error constants defined by Spread (all negative numbers):

ILLEGAL_SPREAD COULD_NOT_CONNECT REJECT_QUOTA REJECT_NO_NAME
REJECT_ILLEGAL_NAME REJECT_NOT_UNIQUE REJECT_VERSION CONNECTION_CLOSED
REJECT_AUTH ILLEGAL_SESSION ILLEGAL_SERVICE ILLEGAL_MESSAGE
ILLEGAL_GROUP BUFFER_TOO_SHORT GROUPS_TOO_SHORT MESSAGE_TOO_LONG

Constants defined by the Python wrapper:

DEFAULT_BUFFER_SIZE - The initial data buffer size used by receive().

DEFAULT_GROUPS_SIZE - The initial group buffer size used by receive().


Methods of MailboxType objects
------------------------------

All these can raise SpreadError upon Spread-related failures.

disconnect() - Disconnect from the mailbox.  The mailbox object should
not be used after this call.

fileno() - Return the integer file descriptor for this mailbox
object.  This can be used for reading in a select call to check for
receivable messages.

join(group) - Join the group with the given name.  Return None.

leave(group) - Leave the group with the given name.  Return None.

multicast(service_type, group, message[, message_type]) - Send a
message to all members of a group.  Arguments: service_type is one of
the integer constants: UNRELIABLE_MESS, RELIABLE_MESS, FIFO_MESS,
CAUSAL_MESS, AGREED_MESS, or SAFE_MESS (see the SP_multicast man page
for their meaning); group: the name of the group to send to; message:
the data to be sent.  (The Python wrapper currently doesn't support
sending data to more than one group at a time.)

receive() - Block (if necessary) until a message is received, and
return an object representing the received message.  The return value
is of type RegularMsgType or MembershipMsgType (see above).  The
caller does not have to worry about buffer sizes; when the underlying
SP_receive() call fails due to a BUFFER_TOO_SHORT or GROUPS_TOO_SHORT
error, the Python wrapper method allocates a buffer of the requested
size and retries the call.

poll() - Return 1 if the receive() method can return a message without
blocking; 0 if no message is available immediately.
