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 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.