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: all arguments are optional: spread_name a string specifying the port and host of the spread daemon to use, of the form "@" or "", where is an integer port number (typically the constant DEFAULT_SPREAD_PORT) represented as a string, and specifies the host where the daemon runs, typically "localhost". The default is the default Spread port and host. private_name a string specifying the name under which this client is to be known; the default is a private name made up by Spread priority 0 or 1, currently unused; default 0 membership 1 to receive membership messages, and 0 to decline receiving those; default 1 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 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: 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 msg_type an int with the value of the message_type argument passed to multicast() (see the SP_receive manpage; this is a signed 16-bit int whose meaning (if any) is wholly up to the application) endian an int that is 0 if there are no endian issues 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 CAUSED_BY_JOIN CAUSED_BY_LEAVE CAUSED_BY_DISCONNECT 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=0]) - Send a message to all members of a group. Return the number of bytes sent. Arguments: service_type one of the integer constants (see the SP_multicast man page for their meaning): UNRELIABLE_MESS RELIABLE_MESS FIFO_MESS CAUSAL_MESS AGREED_MESS SAFE_MESS group the name of the group to send to (the Python wrapper currently doesn't support sending data to more than one group at a time) message the data to be sent, as a Python string message_type a signed integer, which should fit in 16 bits; the application can use this for any purpose it likes, or ignore it; see the SP_multicast manpage 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.