Sava C++/Lua/Perl/Python/Ruby Bindings for Spread API Documentation

1.0.2

For instructions on building the software and information about the Lua, Perl, Python, and Ruby bindings, see:

Licensing

Sava C++/Lua/Perl/Python/Ruby Bindings for Spread is Copyright 2006-2008 by Savarese Software Research Corporation and licensed under the Apache License 2.0 as described in the files accompanying the source distribution:

LICENSE
NOTICE

This product uses software developed by Spread Concepts LLC for use in the Spread toolkit. For more information about Spread, see http://www.spread.org/.

Contact

For inquiries about the software see http://www.savarese.com/contact.html

Overview

Sava C++/Lua/Perl/Python/Ruby Bindings for Spread provides group communication classes that wrap the Spread Toolkit's C API. Even though you can use the Spread C API directly in C++ code, error handling and data structure manipulation can be cumbersome. Sava C++/Lua/Perl/Python/Ruby Bindings for Spread takes some of that pain away by providing automatic operation retries, automatic resizing of message and group buffers, exceptions for true errors, and safe connection management via the "resource acquisition is initialization" idiom.

To use the library add:

#include <sava/libsavaspread.h>

#include <sava/spread.h>

to the top of your C++ source file. The first form will pick up any future additions to the library that fall into a namespace other than sava::spread (e.g., possibly sava::fl_spread). The second form will pick up only the sava::spread namespace. At the moment, there are no additional namespaces, so they are currently equivalent.

The main entry point to using the API is the Mailbox class, which is used to establish a connection with the Spread daemon, join/leave groups, and send/receive messages.

Until the 1.0 release, the API will be in flux and incompatible changes may be introduced between pre-1.0 releases.

Notes

Knowledge of the Spread C API is required to make use of the Sava C++/Lua/Perl/Python/Ruby Bindings for Spread. This documentation does not attempt to explain how to use Spread or how it works. It documents only the C++ API.

Sava C++/Lua/Perl/Python/Ruby Bindings for Spread currently wraps only the SP_ functions from the spread-core library. The flush FL_ functions are not wrapped. Given the similarity of the SP_ and FL_ functions, a future version of the library could use generic programming techniques to wrap both and avoid code duplication. Such a change may break compatibility with earlier versions of the library. If there is user demand to wrap the view synchrony flush API or a patch is submitted, we'll try to do this for a 2.0 release.