Collage  1.7.0
High-performance C++ library for developing object-oriented distributed applications.
co Namespace Reference

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  DataOStream
 A std::ostream-like interface for object serialization. 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< BufferConnectionBufferConnectionPtr
 
typedef lunchbox::RefPtr< const BufferConnectionConstBufferConnectionPtr
 
typedef lunchbox::RefPtr< ObjectCM > ObjectCMPtr
 
typedef uint128_t NodeID
 A unique identifier for nodes.
 
typedef lunchbox::RefPtr< NodeNodePtr
 A reference pointer for Node pointers. More...
 
typedef lunchbox::RefPtr< const NodeConstNodePtr
 A reference pointer for const Node pointers. More...
 
typedef lunchbox::RefPtr< LocalNodeLocalNodePtr
 A reference pointer for LocalNode pointers. More...
 
typedef lunchbox::RefPtr< const LocalNodeConstLocalNodePtr
 A reference pointer for const LocalNode pointers. More...
 
typedef lunchbox::RefPtr< ConnectionConnectionPtr
 A reference pointer for Connection pointers. More...
 
typedef lunchbox::RefPtr< ConnectionDescriptionConnectionDescriptionPtr
 A reference pointer for ConnectionDescription pointers. More...
 
typedef lunchbox::RefPtr< const ConnectionDescriptionConstConnectionDescriptionPtr
 A reference pointer for const ConnectionDescription pointers. More...
 
typedef std::vector< ConnectionListener * > ConnectionListeners
 A vector of ConnectionListener.
 
typedef std::vector< NodePtrNodes
 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< NodeIDNodeIDs
 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< ConnectionPtrConnections
 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< ConnectionDescriptionPtrConnectionDescriptions
 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< ICommandICommands
 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< CommandQueueWorker
 

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

A reference pointer for ConnectionDescription pointers.

Definition at line 95 of file types.h.

A vector of ConnectionDescriptionPtr's.

Definition at line 131 of file types.h.

typedef ConnectionDescriptions::const_iterator co::ConnectionDescriptionsCIter

A const iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 135 of file types.h.

typedef ConnectionDescriptions::iterator co::ConnectionDescriptionsIter

An iterator for a vector of ConnectionDescriptionPtr's.

Definition at line 133 of file types.h.

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

A reference pointer for Connection pointers.

Definition at line 93 of file types.h.

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

A vector of ConnectionPtr's.

Definition at line 124 of file types.h.

typedef Connections::const_iterator co::ConnectionsCIter

A const iterator for a vector of ConnectionPtr's.

Definition at line 126 of file types.h.

typedef Connections::iterator co::ConnectionsIter

An iterator for a vector of ConnectionPtr's.

Definition at line 128 of file types.h.

A reference pointer for const ConnectionDescription pointers.

Definition at line 98 of file types.h.

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

A reference pointer for const LocalNode pointers.

Definition at line 91 of file types.h.

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

A reference pointer for const Node pointers.

Definition at line 87 of file types.h.

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

A vector of input commands.

Definition at line 138 of file types.h.

typedef ICommands::const_iterator co::ICommandsCIter

A const iterator for a vector of input commands.

Definition at line 142 of file types.h.

typedef ICommands::iterator co::ICommandsIter

A iterator for a vector of input commands.

Definition at line 140 of file types.h.

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

A reference pointer for LocalNode pointers.

Definition at line 89 of file types.h.

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

A vector of NodeID's.

Definition at line 110 of file types.h.

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

A reference pointer for Node pointers.

Definition at line 85 of file types.h.

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

A vector of NodePtr's.

Definition at line 103 of file types.h.

typedef Nodes::const_iterator co::NodesCIter

A const iterator for a vector of nodes.

Definition at line 107 of file types.h.

typedef Nodes::iterator co::NodesIter

An iterator for a vector of nodes.

Definition at line 105 of file types.h.

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

A vector of objects.

Definition at line 113 of file types.h.

typedef Objects::const_iterator co::ObjectsCIter

A const iterator for a vector of objects.

Definition at line 117 of file types.h.

typedef Objects::iterator co::ObjectsIter

A iterator for a vector of objects.

Definition at line 115 of file types.h.

Enumeration Type Documentation

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 40 of file commands.h.

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 32 of file commands.h.

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.

lunchbox::Log topic emitted by Collage.

Definition at line 28 of file log.h.

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.

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
dataThe serialized connection descriptions.
descriptionsreturn 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
argcthe command line argument count.
argvthe 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 73 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 104 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: