Collage  1.6.0
High-performance C++ library for developing object-oriented distributed applications.
co::Connection Class Referenceabstract

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

#include <connection.h>

+ Inheritance diagram for co::Connection:
+ Collaboration diagram for co::Connection:

Public Types

enum  State {
  STATE_CLOSED, STATE_CONNECTING, STATE_CONNECTED, STATE_LISTENING,
  STATE_CLOSING
}
 The current state of the Connection. More...
 
typedef int Notifier
 The Notifier used by the ConnectionSet to detect readiness of a Connection.
 

Public Member Functions

virtual Notifier getNotifier () const =0
 
Data Access
CO_API State getState () const
 
bool isClosed () const
 
bool isClosing () const
 
bool isConnected () const
 
bool isListening () const
 
CO_API bool isMulticast () const
 
CO_API ConstConnectionDescriptionPtr getDescription () const
 
bool operator== (const Connection &rhs) const
 
Connection State Changes
virtual bool connect ()
 Connect to the remote peer. More...
 
virtual bool listen ()
 Put the connection into the listening state. More...
 
virtual void close ()
 Close a connected or listening connection. More...
 
void addListener (ConnectionListener *listener)
 
void removeListener (ConnectionListener *listener)
 
Asynchronous accept
virtual void acceptNB ()
 Start an accept operation. More...
 
virtual ConnectionPtr acceptSync ()
 Complete an accept operation. More...
 
Asynchronous read
CO_API void recvNB (BufferPtr buffer, const uint64_t bytes)
 Start a read operation on the connection. More...
 
CO_API bool recvSync (BufferPtr &buffer, const bool block=true)
 Finish reading data from the connection. More...
 
BufferPtr resetRecvData ()
 
Synchronous write to the connection
CO_API bool send (const void *buffer, const uint64_t bytes, const bool isLocked=false)
 Send data using the connection. More...
 
CO_API void lockSend () const
 Lock the connection, no other thread can send data. More...
 
CO_API void unlockSend () const
 Unlock the connection. More...
 
virtual void finish ()
 

Static Public Member Functions

static CO_API ConnectionPtr create (ConnectionDescriptionPtr desc)
 Create a new connection. More...
 

Protected Member Functions

 Connection ()
 Construct a new connection. More...
 
virtual ~Connection ()
 Destruct this connection. More...
 
CO_API void _setDescription (ConnectionDescriptionPtr description)
 
CO_API void _setState (const State state)
 
CO_API ConnectionDescriptionPtr _getDescription ()
 

Low-level IO methods

enum  ReadStatus { READ_TIMEOUT = -2, READ_ERROR = -1 }
 < error codes for readSync()
 
virtual void readNB (void *buffer, const uint64_t bytes)=0
 Start a read operation on the connection. More...
 
virtual int64_t readSync (void *buffer, const uint64_t bytes, const bool block)=0
 Finish reading data from the connection. More...
 
virtual int64_t write (const void *buffer, const uint64_t bytes)=0
 Write data to the connection. More...
 

Detailed Description

An interface definition for communication between hosts.

Connections are stream-oriented communication lines. The parameters of a Connection are described in a ConnectionDescription, which is used in create(), listen() and connect(). A Connection has a Connection::State, which changes when calling listen(), connect() or close(), or whenever the underlying connection is closed by the operating system.

The Connection class defines the interface for connections, various derived classes implement it for the low-level communication protocols, e.g., SocketConnection for TCP/IP or RSPConnection for UDP-based reliable multicast. An implementation may not implement all the functionality defined in this interface.

The Connection is used reference-counted throughout the Collage API.

Definition at line 56 of file connection.h.

Member Enumeration Documentation

The current state of the Connection.

Version
1.0
Enumerator
STATE_CLOSED 

Closed, initial state.

STATE_CONNECTING 

A connect() or listen() is in progress.

STATE_CONNECTED 

The connection has been connected and is open.

STATE_LISTENING 

The connection is listening for connects.

STATE_CLOSING 

A close() is in progress.

Definition at line 59 of file connection.h.

Constructor & Destructor Documentation

co::Connection::Connection ( )
protected

Construct a new connection.

virtual co::Connection::~Connection ( )
protectedvirtual

Destruct this connection.

Member Function Documentation

CO_API ConnectionDescriptionPtr co::Connection::_getDescription ( )
protected
Returns
the description for this connection.
virtual void co::Connection::acceptNB ( )
inlinevirtual

Start an accept operation.

This method returns immediately. The Notifier will signal a new connection request, upon which acceptSync() should be used to finish the accept operation. Only one accept operation might be outstanding, that is, acceptSync() has to be called before the next acceptNB().

See also
acceptSync()
Version
1.0

Definition at line 159 of file connection.h.

virtual ConnectionPtr co::Connection::acceptSync ( )
inlinevirtual

Complete an accept operation.

Returns
the new connection, 0 on error.
Version
1.0

Definition at line 167 of file connection.h.

virtual void co::Connection::close ( )
inlinevirtual

Close a connected or listening connection.

Version
1.0

Definition at line 134 of file connection.h.

virtual bool co::Connection::connect ( )
inlinevirtual

Connect to the remote peer.

The ConnectionDescription of this connection is used to identify the peer's parameters.

Returns
true if the connection was successfully connected, false if not.
Version
1.0

Definition at line 119 of file connection.h.

static CO_API ConnectionPtr co::Connection::create ( ConnectionDescriptionPtr  desc)
static

Create a new connection.

This factory method creates a new concrete connection for the requested type. The description is set on the created Connection.

Parameters
descthe connection parameters.
Returns
the connection.
Version
1.0
CO_API ConstConnectionDescriptionPtr co::Connection::getDescription ( ) const
Returns
the description for this connection.
Version
1.0
virtual Notifier co::Connection::getNotifier ( ) const
pure virtual
Returns
the notifier signaling events.
Version
1.0

Implemented in co::BufferConnection.

CO_API State co::Connection::getState ( ) const
Returns
the State of this connection.
Version
1.0
bool co::Connection::isClosed ( ) const
inline
Returns
true if the connection is closed.
Version
1.0

Definition at line 86 of file connection.h.

bool co::Connection::isClosing ( ) const
inline
Returns
true if the connection is about to close.
Version
1.0

Definition at line 89 of file connection.h.

bool co::Connection::isConnected ( ) const
inline
Returns
true if the connection is connected.
Version
1.0

Definition at line 92 of file connection.h.

bool co::Connection::isListening ( ) const
inline
Returns
true if the connection is listening.
Version
1.0

Definition at line 95 of file connection.h.

CO_API bool co::Connection::isMulticast ( ) const
Returns
true if this is a multicast connection.
Version
1.0
virtual bool co::Connection::listen ( )
inlinevirtual

Put the connection into the listening state.

The ConnectionDescription of this connection is used to identify the listening parameters.

Returns
true if the connection is listening for new incoming connections, false if not.
Version
1.0

Definition at line 131 of file connection.h.

CO_API void co::Connection::lockSend ( ) const

Lock the connection, no other thread can send data.

Version
1.0
virtual void co::Connection::readNB ( void *  buffer,
const uint64_t  bytes 
)
protectedpure virtual

Start a read operation on the connection.

This method is the low-level counterpart used by recvNB(), implemented by the concrete connection.

This function returns immediately. The operation's Notifier will signal data availability, upon which readSync() is used to finish the operation.

Parameters
bufferthe buffer receiving the data.
bytesthe number of bytes to read.
See also
readSync()

Implemented in co::BufferConnection.

virtual int64_t co::Connection::readSync ( void *  buffer,
const uint64_t  bytes,
const bool  block 
)
protectedpure virtual

Finish reading data from the connection.

This method is the low-level counterpart used by recvSync(), implemented by the concrete connection. It may return with a partial read.

Parameters
bufferthe buffer receiving the data.
bytesthe number of bytes to read.
blockinternal WAR parameter, ignore it in the implementation unless you know exactly why not.
Returns
the number of bytes read, or -1 upon error.

Implemented in co::BufferConnection.

CO_API void co::Connection::recvNB ( BufferPtr  buffer,
const uint64_t  bytes 
)

Start a read operation on the connection.

This function returns immediately. The Notifier will signal data availability, upon which recvSync() should be used to finish the operation. The data will be appended to the given buffer. Only one read operation might be outstanding, that is, readSync() has to be called before the next readNB().

Parameters
bufferthe buffer receiving the data.
bytesthe number of bytes to read.
See also
recvSync()
Version
1.0
CO_API bool co::Connection::recvSync ( BufferPtr &  buffer,
const bool  block = true 
)

Finish reading data from the connection.

This function may block even if data availability was signaled, i.e., when only a part of the data requested has been received. The received data is appended to the buffer, at most the number of bytes given to recvNB(). This method uses readNB() and readSync() to fill a buffer, potentially by using multiple reads.

Parameters
bufferreturn value, the buffer passed to recvNB().
blockinternal workaround parameter, do not use unless you know exactly why.
Returns
true if all requested data has been read, false otherwise.
Version
1.0
CO_API bool co::Connection::send ( const void *  buffer,
const uint64_t  bytes,
const bool  isLocked = false 
)

Send data using the connection.

A send may be performed using multiple write() operations. For thread-safe sending from multiple threads it is therefore crucial to protect the send() operation internally. If the connection is not already locked externally, it will use an internal mutex.

Parameters
bufferthe buffer containing the message.
bytesthe number of bytes to send.
isLockedtrue if the connection is locked externally.
Returns
true if all data has been read, false if not.
See also
lockSend(), unlockSend()
Version
1.0
CO_API void co::Connection::unlockSend ( ) const

Unlock the connection.

Version
1.0
virtual int64_t co::Connection::write ( const void *  buffer,
const uint64_t  bytes 
)
protectedpure virtual

Write data to the connection.

This method is the low-level counterpart used by send(), implemented by the concrete connection. It may return with a partial write.

Parameters
bufferthe buffer containing the message.
bytesthe number of bytes to write.
Returns
the number of bytes written, or -1 upon error.

Implemented in co::BufferConnection.


The documentation for this class was generated from the following file: