Object-oriented network library. More...

Classes
class	Array
	A wrapper to (de)serialize arrays. More...
class	Barrier
	A networked, versioned barrier. More...
class	Buffer
	A receive buffer, containing the data for a co::ICommand. 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	Command
class	CommandCache
	A command cache handles the reuse of allocated packets for a node. More...
class	CommandFunc
	A wrapper to register a function callback on an object instance. More...
class	CommandQueue
	A CommandQueue is a thread-safe queue for command packets. More...
class	Compressor
struct	CompressorInfo
class	Connection
	An interface definition for communication between hosts. More...
class	ConnectionDescription
	Describes Connection parameters. More...
class	ConnectionListener
	A listener interface to connection changes. More...
class	ConnectionSet
	Handles events on a set of connections. More...
class	CPUCompressor
class	CustomICommand
	A command specialization for custom commands. More...
class	CustomOCommand
	A class for sending custom commands and data to local & external nodes. More...
class	DataIStream
	A std::istream-like input data stream for binary data. More...
class	DataIStreamArchive
	A boost.serialization archive for a co::DataIStream. More...
class	DataOStream
	A std::ostream buffering and/or retaining data in a binary format. More...
class	DataOStreamArchive
	A boost.serialization archive for a co::DataOStream. More...
class	DataStreamArchiveException
	Exception being thrown when serialization cannot proceed. More...
class	Dispatcher
	A helper class providing command packet dispatch functionality to networked objects. More...
class	ErrorRegistry
	The registry translating error codes to strings. More...
class	Exception
	A base Exception for Collage operations. More...
class	Global
	Global parameter handling for the Collage library. More...
class	ICommand
	A class managing received commands. More...
class	InstanceCache
class	LocalNode
	Specialization of a local node. More...
class	Node
	Manages a node. More...
class	Object
	A generic, 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
	A command specialization for objects. More...
class	ObjectMap
	Central 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...
struct	Packet
	A packet send over the network. More...
struct	NodePacket
	Packet sent to and handled by an co::Node. More...
struct	NodeCommandPacket
	Packet sent to and handled by an co::Node. More...
struct	ObjectPacket
	Packet sent to and handled by an co::Object. More...
class	Plugin
class	PluginRegistry
	The registry for all loaded Equalizer plugins. More...
class	QueueItem
	The item of the distributed queue holding the data. More...
class	QueueMaster
	The producer end of a distributed queue. More...
struct	QueueGetItemPacket
struct	QueueItemPacket
struct	QueueEmptyPacket
class	QueueSlave
	The consumer end of a distributed queue. More...
class	Serializable
	Base class for distributed, inheritable objects. More...
class	Version
	Information about the current Collage version. More...
class	WorkerThread
	A worker thread. More...
class	Zeroconf
	A zeroconf communicator. More...
Functions
std::ostream &	operator<< (std::ostream &, const Buffer &)
CO_API std::ostream &	operator<< (std::ostream &os, const Command &)
std::ostream &	operator<< (std::ostream &, const CommandCache &)
template<typename T >
std::ostream &	operator<< (std::ostream &os, const CommandFunc< T > &func)
std::ostream &	operator<< (std::ostream &os, const CompressorInfo &info)
CO_API std::ostream &	operator<< (std::ostream &, const Connection &)
CO_API std::ostream &	operator<< (std::ostream &, const ConnectionDescription &)
CO_API std::string	serialize (const ConnectionDescriptions &)
	Serialize a vector of connection descriptions to a string.
CO_API bool	deserialize (std::string &data, ConnectionDescriptions &descriptions)
	Deserialize a vector or connection descriptions from a string.
CO_API std::ostream &	operator<< (std::ostream &os, const ConnectionSet *set)
CO_API std::ostream &	operator<< (std::ostream &os, const ConnectionSet::Event event)
std::ostream &	operator<< (std::ostream &os, const ConnectionType &type)
CO_API std::ostream &	operator<< (std::ostream &os, const CustomICommand &)
std::ostream &	operator<< (std::ostream &os, const DataOStream &dataOStream)
CO_API std::ostream &	operator<< (std::ostream &os, const Error &)
	Print the error in a human-readable format.
std::ostream &	operator<< (std::ostream &os, const Exception &e)
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.
CO_API bool	exit ()
	De-initialize the Collage network library.
CO_API std::ostream &	operator<< (std::ostream &, const InstanceCache &)
std::ostream &	operator<< (std::ostream &os, const LocalNode &node)
CO_API std::ostream &	operator<< (std::ostream &os, const Node &node)
CO_API std::ostream &	operator<< (std::ostream &, const Node::State)
std::ostream &	operator<< (std::ostream &os, const NodeType &type)
CO_API std::ostream &	operator<< (std::ostream &, const Object &)
CO_API std::ostream &	operator<< (std::ostream &os, const ObjectICommand &)
std::ostream &	operator<< (std::ostream &os, const ObjectVersion &ov)
std::ostream &	operator<< (std::ostream &os, const Packet *packet)
std::ostream &	operator<< (std::ostream &os, const NodePacket *packet)
std::ostream &	operator<< (std::ostream &os, const ObjectPacket *packet)
Typedefs
typedef UUID	NodeID
	A unique identifier for nodes.
typedef lunchbox::RefPtr< Node >	NodePtr
	A reference pointer for Node pointers.
typedef lunchbox::RefPtr < const Node >	ConstNodePtr
	A reference pointer for const Node pointers.
typedef lunchbox::RefPtr < LocalNode >	LocalNodePtr
	A reference pointer for LocalNode pointers.
typedef lunchbox::RefPtr < const LocalNode >	ConstLocalNodePtr
	A reference pointer for const LocalNode pointers.
typedef lunchbox::RefPtr < Connection >	ConnectionPtr
	A reference pointer for Connection pointers.
typedef lunchbox::RefPtr < ConnectionDescription >	ConnectionDescriptionPtr
	A reference pointer for ConnectionDescription pointers.
typedef std::vector< NodePtr >	Nodes
	A vector of NodePtr's.
typedef Nodes::iterator	NodesIter
	An iterator for a vector of nodes.
typedef Nodes::const_iterator	NodesCIter
	A const iterator for a vector of nodes.
typedef std::vector< Object * >	Objects
	A vector of objects.
typedef Objects::iterator	ObjectsIter
	A iterator for a vector of objects.
typedef Objects::const_iterator	ObjectsCIter
	A const iterator for a vector of objects.
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.
typedef Connections::const_iterator	ConnectionsCIter
	A const iterator for a vector of ConnectionPtr's.
typedef Connections::iterator	ConnectionsIter
	An iterator for a vector of ConnectionPtr's.
typedef std::vector < ConnectionDescriptionPtr >	ConnectionDescriptions
	A vector of ConnectionDescriptionPtr's.
typedef ConnectionDescriptions::iterator	ConnectionDescriptionsIter
	An iterator for a vector of ConnectionDescriptionPtr's.
typedef ConnectionDescriptions::const_iterator	ConnectionDescriptionsCIter
	A const iterator for a vector of ConnectionDescriptionPtr's.
typedef WorkerThread < CommandQueue >	Worker
Enumerations
enum	NodeCommand { CMD_NODE_STOP_RCV, CMD_NODE_STOP_CMD, CMD_NODE_SET_AFFINITY_RCV, CMD_NODE_SET_AFFINITY_CMD, CMD_NODE_MESSAGE, CMD_NODE_CONNECT, CMD_NODE_CONNECT_REPLY, CMD_NODE_CONNECT_ACK, CMD_NODE_ID, CMD_NODE_DISCONNECT, CMD_NODE_GET_NODE_DATA, CMD_NODE_GET_NODE_DATA_REPLY, CMD_NODE_ACQUIRE_SEND_TOKEN, CMD_NODE_ACQUIRE_SEND_TOKEN_REPLY, CMD_NODE_RELEASE_SEND_TOKEN, CMD_NODE_ADD_LISTENER, CMD_NODE_REMOVE_LISTENER, CMD_NODE_ACK_REQUEST, CMD_NODE_FIND_MASTER_NODE_ID, CMD_NODE_FIND_MASTER_NODE_ID_REPLY, CMD_NODE_ATTACH_OBJECT, CMD_NODE_DETACH_OBJECT, CMD_NODE_REGISTER_OBJECT, CMD_NODE_DEREGISTER_OBJECT, CMD_NODE_MAP_OBJECT, CMD_NODE_MAP_OBJECT_SUCCESS, CMD_NODE_MAP_OBJECT_REPLY, CMD_NODE_UNMAP_OBJECT, CMD_NODE_UNSUBSCRIBE_OBJECT, CMD_NODE_OBJECT_INSTANCE, CMD_NODE_OBJECT_INSTANCE_MAP, CMD_NODE_OBJECT_INSTANCE_COMMIT, CMD_NODE_OBJECT_INSTANCE_PUSH, CMD_NODE_DISABLE_SEND_ON_REGISTER, CMD_NODE_REMOVE_NODE, CMD_NODE_OBJECT_PUSH, CMD_NODE_PING, CMD_NODE_PING_REPLY, CMD_NODE_COMMAND, CMD_NODE_CUSTOM = 50 }
enum	ObjectCommand { CMD_OBJECT_INSTANCE, CMD_OBJECT_DELTA, CMD_OBJECT_SLAVE_DELTA, CMD_OBJECT_COMMIT, CMD_OBJECT_PUSH, CMD_OBJECT_OBSOLETE, CMD_OBJECT_MAX_VERSION, CMD_OBJECT_CUSTOM = 10 }
enum	BarrierCommand { CMD_BARRIER_ENTER = CMD_OBJECT_CUSTOM, CMD_BARRIER_ENTER_REPLY, CMD_BARRIER_CUSTOM = 20 }
enum	QueueCommand { CMD_QUEUE_GET_ITEM = CMD_OBJECT_CUSTOM, CMD_QUEUE_EMPTY, CMD_QUEUE_ITEM, CMD_QUEUE_CUSTOM = 20, CMD_QUEUE_GET_ITEM = CMD_OBJECT_CUSTOM, CMD_QUEUE_EMPTY, CMD_QUEUE_ITEM, CMD_QUEUE_CUSTOM = 20 }
enum	ConnectionType { CONNECTIONTYPE_NONE = 0, CONNECTIONTYPE_TCPIP, CONNECTIONTYPE_SDP, CONNECTIONTYPE_PIPE, CONNECTIONTYPE_NAMEDPIPE, CONNECTIONTYPE_IB, CONNECTIONTYPE_RDMA, CONNECTIONTYPE_UDT, CONNECTIONTYPE_MULTICAST = 0x100, CONNECTIONTYPE_PGM, CONNECTIONTYPE_RSP }
	The supported network protocols. More...
enum	Error { ERROR_NONE = 0, ERROR_CUSTOM = LB_16KB }
	Defines errors produced by Collage base classes. More...
enum	LogTopics { LOG_OBJECTS = lunchbox::LOG_CUSTOM << 0, LOG_BARRIER = lunchbox::LOG_CUSTOM << 1, LOG_RSP = lunchbox::LOG_CUSTOM << 2, LOG_PACKETS = lunchbox::LOG_CUSTOM << 3, LOG_PLUGIN = lunchbox::LOG_CUSTOM << 4, LOG_CUSTOM = lunchbox::LOG_CUSTOM << 5 }
enum	NodeType { NODETYPE_CO_INVALID, NODETYPE_CO_NODE, NODETYPE_CO_USER = 0x100 }
	Node types to identify connecting nodes. More...
enum	ObjectType { OBJECTTYPE_NONE, OBJECTTYPE_CUSTOM = 16 }
enum	ObjectCommands { CMD_OBJECT_INSTANCE, CMD_OBJECT_DELTA, CMD_OBJECT_SLAVE_DELTA, CMD_OBJECT_MAX_VERSION }
enum	PacketType { PACKETTYPE_CO_NODE, PACKETTYPE_CO_OBJECT, PACKETTYPE_CO_CUSTOM = 1<<7 }
enum	QueueCommand { CMD_QUEUE_GET_ITEM = CMD_OBJECT_CUSTOM, CMD_QUEUE_EMPTY, CMD_QUEUE_ITEM, CMD_QUEUE_CUSTOM = 20, CMD_QUEUE_GET_ITEM = CMD_OBJECT_CUSTOM, CMD_QUEUE_EMPTY, CMD_QUEUE_ITEM, CMD_QUEUE_CUSTOM = 20 }
Variables
const signed char	magicByte = 'c' \| 'o'
const unsigned	no_infnan = 64
CO_API const uint128_t	VERSION_NONE
	Special object version values.
CO_API const uint128_t	VERSION_FIRST
CO_API const uint128_t	VERSION_NEXT
CO_API const uint128_t	VERSION_INVALID
CO_API const uint128_t	VERSION_OLDEST
CO_API const uint128_t	VERSION_HEAD

Detailed Description

Object-oriented network library.

Collage is a cross-platform C++ library for building heterogenous, distributed applications. It is used as the cluster backend for Equalizer. Collage provides an abstraction of different network connections, peer-to-peer messaging, discovery and synchronization as well as 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 stream between two 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.

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, a Packet is send using the remote node proxy. The remote local node receives the packet, wraps it in a Command, 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 packet specializations NodePacket and ObjectPacket dispatch the packet to the LocalNode or a registered Object, respectively.

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, potentially on other nodes. Objects can be static or versioned. Versioned objects can commit new versions, sync committed versions and can send object packets to other instances.

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

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.

CO_API bool co::exit ( )

De-initialize the Collage network library.

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

bool co::init	(	const int	argc,
		char **	argv
	)		`[inline]`

Initialize the Collage network library.

Parameters:

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

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

Definition at line 38 of file init.h.

References co::Version::getABI().

Here is the call graph for this function:

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

Print the error in a human-readable format.

Version:: 1.0

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

Serialize a vector of connection descriptions to a string.

Typedef Documentation

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

A reference pointer for ConnectionDescription pointers.

Definition at line 86 of file types.h.

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

A vector of ConnectionDescriptionPtr's.

Definition at line 114 of file types.h.

typedef ConnectionDescriptions::const_iterator co::ConnectionDescriptionsCIter

A const iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 118 of file types.h.

typedef ConnectionDescriptions::iterator co::ConnectionDescriptionsIter

An iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 116 of file types.h.

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

A reference pointer for Connection pointers.

Definition at line 84 of file types.h.

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

A vector of ConnectionPtr's.

Definition at line 107 of file types.h.

typedef Connections::const_iterator co::ConnectionsCIter

A const iterator for a vector of ConnectionPtr's.

Definition at line 109 of file types.h.

typedef Connections::iterator co::ConnectionsIter

An iterator for a vector of ConnectionPtr's.

Definition at line 111 of file types.h.

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

A reference pointer for const LocalNode pointers.

Definition at line 82 of file types.h.

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

A reference pointer for const Node pointers.

Definition at line 78 of file types.h.

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

A reference pointer for LocalNode pointers.

Definition at line 80 of file types.h.

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

A reference pointer for Node pointers.

Definition at line 76 of file types.h.

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

A vector of NodePtr's.

Definition at line 89 of file types.h.

typedef Nodes::const_iterator co::NodesCIter

A const iterator for a vector of nodes.

Definition at line 93 of file types.h.

typedef Nodes::iterator co::NodesIter

An iterator for a vector of nodes.

Definition at line 91 of file types.h.

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

A vector of objects.

Definition at line 96 of file types.h.

typedef Objects::const_iterator co::ObjectsCIter

A const iterator for a vector of objects.

Definition at line 100 of file types.h.

typedef Objects::iterator co::ObjectsIter

A iterator for a vector of objects.

Definition at line 98 of file types.h.

Enumeration Type Documentation

enum co::ConnectionType

The supported network protocols.

Enumerator:

CONNECTIONTYPE_TCPIP	TCP/IP sockets.
CONNECTIONTYPE_SDP	SDP sockets (InfiniBand)
CONNECTIONTYPE_PIPE	pipe() based uni-directional connection
CONNECTIONTYPE_NAMEDPIPE	Named pipe based bidirectional connection.
CONNECTIONTYPE_IB	Infiniband based RDMA.
CONNECTIONTYPE_RDMA	Infiniband RDMA CM.
CONNECTIONTYPE_UDT	UDT connection.
CONNECTIONTYPE_PGM	IP-based multicast connection (PGM)
CONNECTIONTYPE_RSP	UDP-based reliable stream protocol.