Documentation

Spread is a group communication system that provides a number of messaging services to applications. These services can then be used by applications to make it easy to write full-featured reliable groupware, distributed servers, client-server applications, chat and news services, and many other networked enabled tools.

Some of the most useful services Spread provides:

• Efficient and reliable message bus.
• Reliable multicast from any number of senders to lots of receivers.
• Scalable group services that allow thousands of active groups.
• Membership services that inform each component of an application of which other components are running, and enables easy recovery when some fail.
• Agreed ordering of messages to the group - all receivers receive messages sent to the group in exactly the same order. For many document or message based applications this avoids a lot of work that used to be required for the application to order messages for usability or reliability reasons.
• FIFO ordering of data streams allows applications to easily add networked streaming multimedia such as video or audio without having to make changes to existing codes or libraries that expect an in-order stream with no holes because of dropped packets on the network.

For more information about Spread, read the Spread Overview.

An updated version of the Spread Users Guide has been released. It currently documents the C and Java interfaces to Spread and the Events library. It also contains an introduction to Spread, information on configuring Spread for a variety of network environments and hints and tricks for using Spread effectivly in harsh conditions.

A good place to look first is in the FAQ. If you have questions not answered by the FAQ or the below API docs, please join our mailing list at http://lists.spread.org/mailman/listinfo/spread-users or read the archives at http://lists.spread.org/pipermail/spread-users/.

An additional archive of the spread-users mailing list can be found at the Gmame site

If you want to ask us a question directly, please email us at spread@spread.org.

Spread can be used for applications which require high reliability and online recovery from failures in any of the network, hosts, or processes, or for applications with little or no fault-tolerant requirements. The model of Group Communications provides a rich framework for building highly-reliable applications, we currently are working on more documentation about theses uses of Spread, but for now we suggest the following sources:

• The Spread Toolkit: Architecture and Performance
  Yair Amir, Claudiu Danilov, Michal Miskin-Amir, John Schultz, and Jonathan Stanton
  ps, ps.gz, pdf. Johns Hopkins University, Center for Networking and Distributed Systems (CNDS) Technical report CNDS-2004-1.
  
• A Low Latency, Loss Tolerant Architecture and Protocol for Wide Area Group Communication
  Yair Amir, Claudiu Danilov, and Jonathan Stanton
  ps, ps.gz, pdf. Published in International Conference on Dependable Systems and Networks (FTCS-30, DCCA-8), New York, New York, June 25-28, 2000.
  ps, ps.gz, pdf. A full version of this paper was published as Johns Hopkins University, Center for Networking and Distributed Systems (CNDS) Technical report CNDS-99-2.
  
• The Spread Wide Area Group Communication System
  Yair Amir and Jonathan Stanton.
  Technical Report CNDS-98-4, The Center for Networking and Distributed Systems, The Johns Hopkins University.
• Yair Amir's PhD thesis (in PostScript)
• The Extended Virtual Synchrony paper (in PostScript)

C/C++ Documentation

For use in multicast applications where fault-tolerance is not required, usually all that is needed is some api docs and some example code. Below is html documentation of the Spread API, and links to several small sample programs that use some or all of the calls in the API.

This document explains the user level interface to the Spread Toolkit as specified in the header file "sp.h". This document assumes a knowledge of the ideas behind group communication, and explains the specifics of using the Spread Toolkit. For background and more info please read the README that comes with the Spread package.

1. Endian Conversion
2. Event Interface
3. Message Types for Data and Membership Messages
4. Message Type Access Functions
5. Error Return Codes
6. Types Used in Function Prototypes
7. Spread Function Interface
8. Spread daemon
9. spuser program
10. sptuser program
11. spflooder program
12. spmonitor program
13. libspread library

We currently have several useful sample programs available here.

User ( user.c )

is a terminal program that allows one to join and leave groups, send several types of messages and see how membership changes. It uses all the Spread calls.

Flooder ( flooder.c )

is a test program that sends a stream of messages of specified size and type to Spread and receives them while calculating some performance measurements.

Monitor ( monitor.c )

is a terminal program that allows the user to monitor any active Spread daemon and check the state of messages as well as artificially creating network partitions or tuning the daemon for your network.

Java documentation

The Java interface to spread includes all the features of the C interface, as well as some uniquely Java style constructs such as message listeners and an object-oriented design. The Spread Daemon is written in C only, however the library that applications link to is written as both a native C library and a native Java library.

The complete Java documentation can be found on the web, or is part of the Spread download package.

Python Documentation

The Python interface is documented in the python download. Web accessable documentation is also available.