Object-oriented network library. More...

Classes
class	Barrier
	A networked, versioned barrier. More...

class	Buffer
	A receive buffer for a Connection. More...

class	BufferConnection
	A proxy connection buffering outgoing data into a memory buffer. More...

class	BufferListener
	A listener interface to buffer state changes. More...

class	CommandFunc
	A wrapper to register a function callback on an object instance. More...

class	CommandQueue
	A thread-safe, blocking queue for ICommand buffers. More...

class	Connection
	An interface definition for communication between hosts. More...

class	ConnectionDescription
	Describes Connection parameters. More...

class	ConnectionSet
	Handles events on a set of connections. More...

class	CustomICommand
	An input command specialization for custom commands. More...

class	CustomOCommand
	A class for sending custom commands and data to nodes. More...

class	DataIStream
	A std::istream-like input data stream for binary data. More...

class	DataIStreamArchive
	A boost.serialization input archive reading from a co::DataIStream. More...

class	DataOStream
	A std::ostream-like interface for object serialization. More...

class	DataOStreamArchive
	A boost.serialization output archive writing to a co::DataOStream. More...

class	DataStreamArchiveException
	Exception thrown when serialization cannot proceed. More...

class	Dispatcher
	A class providing command dispatch functionality to networked objects. More...

class	Distributable
	Distributable Collage object for any servus::Serializable object. More...

class	Exception
	A base Exception class for Collage operations. More...

class	Global
	Global parameter handling for the Collage library. More...

class	ICommand
	A class managing received commands. More...

class	LocalNode
	Node specialization for a local node. More...

class	Node
	Proxy node representing a remote LocalNode. More...

class	Object
	A distributed object. More...

class	ObjectFactory
	The interface to create objects, used by ObjectMap. More...

class	ObjectHandler
	Interface for entities which map and register objects. More...

class	ObjectICommand
	An input command specialization for objects. More...

class	ObjectMap
	A distributed object registry. More...

class	ObjectOCommand
	A class for sending commands and data to local & external objects. More...

struct	ObjectVersion
	A helper struct bundling an object identifier and version. More...

class	OCommand
	A class for sending commands with data to local and external nodes. More...

class	QueueItem
	The item of the distributed queue holding the data. More...

class	QueueMaster
	The producer end of a distributed queue. More...

class	QueueSlave
	The consumer end of a distributed queue. More...

class	SendToken

class	Serializable
	Base class for distributed, inheritable objects. More...

class	Version
	Information about the current Collage version. More...

class	WorkerThread
	A worker thread processing items out of a CommandQueue. More...

class	Zeroconf
	A zeroconf communicator. More...

Typedefs
typedef lunchbox::RefPtr< BufferConnection >	BufferConnectionPtr

typedef lunchbox::RefPtr< const BufferConnection >	ConstBufferConnectionPtr

typedef lunchbox::RefPtr< ObjectCM >	ObjectCMPtr

typedef uint128_t	NodeID
	A unique identifier for nodes.

typedef lunchbox::RefPtr< Node >	NodePtr
	A reference pointer for Node pointers. More...

typedef lunchbox::RefPtr< const Node >	ConstNodePtr
	A reference pointer for const Node pointers. More...

typedef lunchbox::RefPtr< LocalNode >	LocalNodePtr
	A reference pointer for LocalNode pointers. More...

typedef lunchbox::RefPtr< const LocalNode >	ConstLocalNodePtr
	A reference pointer for const LocalNode pointers. More...

typedef lunchbox::RefPtr< Connection >	ConnectionPtr
	A reference pointer for Connection pointers. More...

typedef lunchbox::RefPtr< ConnectionDescription >	ConnectionDescriptionPtr
	A reference pointer for ConnectionDescription pointers. More...

typedef lunchbox::RefPtr< const ConnectionDescription >	ConstConnectionDescriptionPtr
	A reference pointer for const ConnectionDescription pointers. More...

typedef std::vector< ConnectionListener * >	ConnectionListeners
	A vector of ConnectionListener.

typedef std::vector< NodePtr >	Nodes
	A vector of NodePtr's. More...

typedef Nodes::iterator	NodesIter
	An iterator for a vector of nodes. More...

typedef Nodes::const_iterator	NodesCIter
	A const iterator for a vector of nodes. More...

typedef std::vector< NodeID >	NodeIDs
	A vector of NodeID's. More...

typedef std::vector< Object * >	Objects
	A vector of objects. More...

typedef Objects::iterator	ObjectsIter
	A iterator for a vector of objects. More...

typedef Objects::const_iterator	ObjectsCIter
	A const iterator for a vector of objects. More...

typedef std::vector< Barrier * >	Barriers
	A vector of barriers.

typedef Barriers::iterator	BarriersIter
	Barriers iterator.

typedef Barriers::const_iterator	BarriersCIter
	Barriers const iterator.

typedef std::vector< ConnectionPtr >	Connections
	A vector of ConnectionPtr's. More...

typedef Connections::const_iterator	ConnectionsCIter
	A const iterator for a vector of ConnectionPtr's. More...

typedef Connections::iterator	ConnectionsIter
	An iterator for a vector of ConnectionPtr's. More...

typedef std::vector< ConnectionDescriptionPtr >	ConnectionDescriptions
	A vector of ConnectionDescriptionPtr's. More...

typedef ConnectionDescriptions::iterator	ConnectionDescriptionsIter
	An iterator for a vector of ConnectionDescriptionPtr's. More...

typedef ConnectionDescriptions::const_iterator	ConnectionDescriptionsCIter
	A const iterator for a vector of ConnectionDescriptionPtr's. More...

typedef std::vector< ICommand >	ICommands
	A vector of input commands. More...

typedef ICommands::iterator	ICommandsIter
	A iterator for a vector of input commands. More...

typedef ICommands::const_iterator	ICommandsCIter
	A const iterator for a vector of input commands. More...

typedef WorkerThread< CommandQueue >	Worker

Enumerations
enum	CommandType { COMMANDTYPE_NODE, COMMANDTYPE_OBJECT, COMMANDTYPE_CUSTOM = 1<<7, COMMANDTYPE_INVALID = 0xFFFFFFFFu }
	The type of a Command. More...

enum	Commands { CMD_NODE_CUSTOM = 50, CMD_NODE_MAXIMUM = 0xFFFFFFu, CMD_OBJECT_CUSTOM = 10, CMD_INVALID = 0xFFFFFFFFu }

enum	ConnectionType { CONNECTIONTYPE_NONE = 0, CONNECTIONTYPE_TCPIP, CONNECTIONTYPE_PIPE, CONNECTIONTYPE_NAMEDPIPE, CONNECTIONTYPE_IB, CONNECTIONTYPE_RDMA, CONNECTIONTYPE_UDT, CONNECTIONTYPE_MULTICAST = 0x100, CONNECTIONTYPE_RSP }
	The supported network protocols. More...

enum	LogTopics { LOG_BUG = lunchbox::LOG_BUG, LOG_OBJECTS = pression::LOG_CUSTOM << 0, LOG_BARRIER = pression::LOG_CUSTOM << 1, LOG_RSP = pression::LOG_CUSTOM << 2, LOG_PACKETS = pression::LOG_CUSTOM << 3, LOG_CUSTOM = pression::LOG_CUSTOM << 5 }
	lunchbox::Log topic emitted by Collage. More...

enum	NodeType { NODETYPE_INVALID, NODETYPE_NODE, NODETYPE_USER = 0x100 }
	Node types to identify connecting nodes. More...

enum	ObjectType { OBJECTTYPE_NONE, OBJECTTYPE_CUSTOM = 16 }

Functions
std::ostream &	operator<< (std::ostream &, const Buffer &)

template<typename T >
std::ostream &	operator<< (std::ostream &os, const CommandFunc< T > &func)
	Output the given CommandFunc. More...

CO_API std::ostream &	operator<< (std::ostream &, const Connection &)

CO_API std::ostream &	operator<< (std::ostream &, const ConnectionDescription &)
	Output the given description in human-readable format. More...

CO_API std::string	serialize (const ConnectionDescriptions &)
	Serialize a vector of connection descriptions to a string. More...

CO_API bool	deserialize (std::string &data, ConnectionDescriptions &descriptions)
	Deserialize a vector or connection descriptions from a string. More...

CO_API std::ostream &	operator<< (std::ostream &, const ConnectionSet &)

CO_API std::ostream &	operator<< (std::ostream &, const ConnectionSet::Event)

std::ostream &	operator<< (std::ostream &os, const ConnectionType &type)

CO_API std::ostream &	operator<< (std::ostream &os, const CustomICommand &)

template<class T >
std::ostream &	operator<< (std::ostream &os, const Distributable< T > &object)

std::ostream &	operator<< (std::ostream &os, const Exception &e)
	Output the exception in human-readable form. More...

CO_API std::ostream &	operator<< (std::ostream &os, const ICommand &)

CO_API bool	_init (const int argc, char **argv)

bool	init (const int argc, char **argv)
	Initialize the Collage network library. More...

CO_API bool	exit ()
	De-initialize the Collage network library. More...

std::ostream &	operator<< (std::ostream &os, const LocalNode &node)

CO_API std::ostream &	operator<< (std::ostream &os, const Node &node)

std::ostream &	operator<< (std::ostream &os, const NodeType &type)

CO_API std::ostream &	operator<< (std::ostream &, const Object &)
	Output information about the object to the given stream. More...

CO_API std::ostream &	operator<< (std::ostream &, const Object::ChangeType &)
	Output object change type in human-readably form. More...

CO_API std::ostream &	operator<< (std::ostream &os, const ObjectICommand &)
	Output information about the object input command. More...

static const uint128_t	VERSION_NONE (0, 0)
	Special object version values.

static const uint128_t	VERSION_FIRST (0, 1)

static const uint128_t	VERSION_NEWEST (0, 0xfffffffffffffffbull)

static const uint128_t	VERSION_OLDEST (0, 0xfffffffffffffffcull)

static const uint128_t	VERSION_NEXT (0, 0xfffffffffffffffdull)

static const uint128_t	VERSION_INVALID (0, 0xfffffffffffffffeull)

static const uint128_t	VERSION_HEAD (0, 0xffffffffffffffffull)

std::ostream &	operator<< (std::ostream &os, const ObjectVersion &ov)

Variables
static const size_t	COMMAND_MINSIZE = 256

static const size_t	COMMAND_ALLOCSIZE = 4096

Detailed Description

Object-oriented network library.

Collage is a cross-platform C++ library for building heterogenous, distributed applications. Among other things, it is the cluster backend for the Equalizer parallel rendering framework. Collage provides an abstraction of different network connections, peer-to-peer messaging, node discovery, synchronization and high-performance, object-oriented, versioned data distribution. Collage is designed for low-overhead multi-threaded execution which allows applications to easily exploit multi-core architectures.

On the lowest layer, Collage provides the Connection, which implements a stream-oriented communication primitive between endpoints. Various protocols are implemented, and can be created using Connection::create with a ConnectionDescription using the corresponding ConnectionType and related parameters. A ConnectionSet may be used to demultiplex input from a set of connections.

The next abstraction in Collage offers peer-to-peer communication between processes, represented by Node and LocalNode. A process typically uses one LocalNode to listen on connection requests and to communicate with other nodes. A Node is a proxy for a remote LocalNode. To exchange information, an OCommand is send using the node proxy. The remote local node receives it as an ICommand and dispatches it to a CommandQueue. The queue is processed by another thread, which invokes a CommandFunc. The queue and handler method are pre-registered with the proper Dispatcher. The command specializations ObjectOCommand and ObjectICommand dispatch the command to a registered Object.

The Object facilitates the data distribution for C++ classes. An object is registered with a listening LocalNode, which allows the mapping of this object to other instances, on the same node or other nodes. Objects can be static or versioned. Versioned objects can commit new versions, sync committed versions and can send object commands to other instances.

The following Figure depicts the UML class diagram of the major Collage classes:

Typedef Documentation

typedef lunchbox::RefPtr< ConnectionDescription > co::ConnectionDescriptionPtr

A reference pointer for ConnectionDescription pointers.

Definition at line 96 of file types.h.

typedef std::vector< ConnectionDescriptionPtr > co::ConnectionDescriptions

A vector of ConnectionDescriptionPtr's.

Definition at line 132 of file types.h.

typedef ConnectionDescriptions::const_iterator co::ConnectionDescriptionsCIter

A const iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 136 of file types.h.

typedef ConnectionDescriptions::iterator co::ConnectionDescriptionsIter

An iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 134 of file types.h.

typedef lunchbox::RefPtr< Connection > co::ConnectionPtr

A reference pointer for Connection pointers.

Definition at line 94 of file types.h.

typedef std::vector< ConnectionPtr > co::Connections

A vector of ConnectionPtr's.

Definition at line 125 of file types.h.

typedef Connections::const_iterator co::ConnectionsCIter

A const iterator for a vector of ConnectionPtr's.

Definition at line 127 of file types.h.

typedef Connections::iterator co::ConnectionsIter

An iterator for a vector of ConnectionPtr's.

Definition at line 129 of file types.h.

typedef lunchbox::RefPtr< const ConnectionDescription > co::ConstConnectionDescriptionPtr

A reference pointer for const ConnectionDescription pointers.

Definition at line 99 of file types.h.

typedef lunchbox::RefPtr< const LocalNode > co::ConstLocalNodePtr

A reference pointer for const LocalNode pointers.

Definition at line 92 of file types.h.

typedef lunchbox::RefPtr< const Node > co::ConstNodePtr

A reference pointer for const Node pointers.

Definition at line 88 of file types.h.

typedef std::vector< ICommand > co::ICommands

A vector of input commands.

Definition at line 139 of file types.h.

typedef ICommands::const_iterator co::ICommandsCIter

A const iterator for a vector of input commands.

Definition at line 143 of file types.h.

typedef ICommands::iterator co::ICommandsIter

A iterator for a vector of input commands.

Definition at line 141 of file types.h.

typedef lunchbox::RefPtr< LocalNode > co::LocalNodePtr

A reference pointer for LocalNode pointers.

Definition at line 90 of file types.h.

typedef std::vector< NodeID > co::NodeIDs

A vector of NodeID's.

Definition at line 111 of file types.h.

typedef lunchbox::RefPtr< Node > co::NodePtr

A reference pointer for Node pointers.

Definition at line 86 of file types.h.

typedef std::vector< NodePtr > co::Nodes

A vector of NodePtr's.

Definition at line 104 of file types.h.

typedef Nodes::const_iterator co::NodesCIter

A const iterator for a vector of nodes.

Definition at line 108 of file types.h.

typedef Nodes::iterator co::NodesIter

An iterator for a vector of nodes.

Definition at line 106 of file types.h.

typedef std::vector< Object* > co::Objects

A vector of objects.

Definition at line 114 of file types.h.

typedef Objects::const_iterator co::ObjectsCIter

A const iterator for a vector of objects.

Definition at line 118 of file types.h.

typedef Objects::iterator co::ObjectsIter

A iterator for a vector of objects.

Definition at line 116 of file types.h.

Enumeration Type Documentation

enum co::Commands

Enumerator
CMD_NODE_CUSTOM	Commands for Node subclasses start here.
CMD_NODE_MAXIMUM	Highest allowed node command (2^24-1)
CMD_OBJECT_CUSTOM	Commands for Object subclasses start here.

Definition at line 41 of file commands.h.

enum co::CommandType

The type of a Command.

Applications can define their own types starting at COMMANDTYPE_CUSTOM.

Enumerator
COMMANDTYPE_NODE	A Node/LocalNode command.
COMMANDTYPE_OBJECT	An Object command.

Definition at line 33 of file commands.h.

enum co::ConnectionType

The supported network protocols.

Enumerator
CONNECTIONTYPE_TCPIP	TCP/IP sockets.
CONNECTIONTYPE_PIPE	pipe() based uni-directional connection
CONNECTIONTYPE_NAMEDPIPE	Named pipe based bidirectional connection.
CONNECTIONTYPE_IB	Deprecated: Win XP Infiniband RDMA
CONNECTIONTYPE_RDMA	Infiniband RDMA CM.
CONNECTIONTYPE_UDT	UDT connection.
CONNECTIONTYPE_RSP	UDP-based reliable stream protocol.

Definition at line 29 of file connectionType.h.

enum co::LogTopics

lunchbox::Log topic emitted by Collage.

Definition at line 28 of file log.h.

enum co::NodeType

Node types to identify connecting nodes.

Version: 1.0

Enumerator
NODETYPE_INVALID	Invalid type.
NODETYPE_NODE	A plain co::Node.
NODETYPE_USER	Application-specific types.

Definition at line 28 of file nodeType.h.

enum co::ObjectType

Enumerator
OBJECTTYPE_CUSTOM	Application-defined objects.

Definition at line 28 of file objectFactory.h.

Function Documentation

CO_API bool co::deserialize	(	std::string &	data,
		ConnectionDescriptions &	descriptions
	)

Deserialize a vector or connection descriptions from a string.

Consumes the data.

Parameters

data	The serialized connection descriptions.
descriptions	return value, deserialized connection descriptions.

Returns: true on successful parsing, false otherwise.

Referenced by co::Node::isLocal(), co::ConnectionDescription::operator!=(), and co::Serializable::operator=().

Here is the caller graph for this function:

CO_API bool co::exit ( )

De-initialize the Collage network library.

Returns: true if the library was successfully de-initialised, false otherwise.

Version: 1.0

Referenced by init().

Here is the caller graph for this function:

bool co::init	(	const int	argc,
		char **	argv
	)

inline

Initialize the Collage network library.

exit() should be called independent of the return value of this function.

Parameters

argc	the command line argument count.
argv	the command line argument values.

Returns: true if the library was successfully initialised, false otherwise

Version: 1.0

Definition at line 42 of file init.h.

References CO_VERSION_ABI, exit(), and co::Version::getABI().

Here is the call graph for this function:

CO_API std::ostream& co::operator<<	(	std::ostream &	os,
		const ObjectICommand &
	)

Output information about the object input command.

Version: 1.0

std::ostream& co::operator<<	(	std::ostream &	os,
		const Exception &	e
	)

inline

Output the exception in human-readable form.

Version: 1.0

Definition at line 72 of file exception.h.

References co::Exception::what().

Here is the call graph for this function:

template<typename T >

std::ostream& co::operator<<	(	std::ostream &	os,
		const CommandFunc< T > &	func
	)

inline

Output the given CommandFunc.

Definition at line 94 of file commandFunc.h.

CO_API std::ostream& co::operator<<	(	std::ostream &	,
		const ConnectionDescription &
	)

Output the given description in human-readable format.

CO_API std::ostream& co::operator<<	(	std::ostream &	,
		const Object &
	)

Output information about the object to the given stream.

Version: 1.0

CO_API std::ostream& co::operator<<	(	std::ostream &	,
		const Object::ChangeType &
	)

Output object change type in human-readably form.

Version: 1.0

CO_API std::string co::serialize ( const ConnectionDescriptions & )

Serialize a vector of connection descriptions to a string.

Referenced by co::Serializable::getInstanceData(), co::Node::isLocal(), and co::Serializable::operator=().

Here is the caller graph for this function:

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation