Collage  0.6.1
Public Member Functions | Static Public Member Functions | Public Types | Protected Member Functions | Protected Attributes | Protected Types
co::Connection Class Reference

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

#include <connection.h>

+ Inheritance diagram for co::Connection:

List of all members.

Public Member Functions

virtual Notifier getNotifier () const =0
template<typename T >
bool send (Packet &packet, const std::vector< T > &data)
Data Access
State getState () const
bool isClosed () const
bool isConnected () const
bool isListening () const
CO_API void setDescription (ConnectionDescriptionPtr description)
 Set the connection parameter description.
CO_API ConnectionDescriptionPtr getDescription () const
bool operator== (const Connection &rhs) const
Connection State Changes
virtual bool connect ()
 Connect to the remote peer.
virtual bool listen ()
 Put the connection into the listening state.
virtual void close ()
 Close a connected or listening connection.
Listener Interface
void addListener (ConnectionListener *listener)
 Add a listener for connection state changes.
void removeListener (ConnectionListener *listener)
 Remove a listener for connection state changes.
Asynchronous accept
virtual void acceptNB ()
 Start an accept operation.
virtual ConnectionPtr acceptSync ()
 Complete an accept operation.
Asynchronous read
CO_API void recvNB (void *buffer, const uint64_t bytes)
 Start a read operation on the connection.
CO_API bool recvSync (void **buffer, uint64_t *bytes, const bool block=true)
 Finish reading data from the connection.
void getRecvData (void **buffer, uint64_t *bytes)
virtual void readNB (void *buffer, const uint64_t bytes)=0
 Start a read operation on the connection.
virtual int64_t readSync (void *buffer, const uint64_t bytes, const bool block)=0
 Finish reading data from the connection.

Static Public Member Functions

static CO_API ConnectionPtr create (ConnectionDescriptionPtr description)
 Create a new 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.

Protected Member Functions

void _fireStateChanged ()

Protected Attributes

State _state
 The connection state.
ConnectionDescriptionPtr _description
 The connection parameters.
lunchbox::Lock _sendLock
 The lock used to protect multiple write calls.

Protected Types

enum  ReadStatus { READ_TIMEOUT = -2, READ_ERROR = -1 }

Synchronous write to the connection

static CO_API bool send (const Connections &connections, const Packet &packet, const bool isLocked=false)
 Sends a packaged message to multiple connections.
static CO_API bool send (const Connections &connections, Packet &packet, const void *data, const uint64_t size, const bool isLocked=false)
 Sends a packaged message including additional data to multiple connections.
static bool CO_API send (const Connections &connections, Packet &packet, const void *const *items, const uint64_t *itemSizes, const size_t nItems)
 Sends a packaged message including additional, multiple data items to multiple connections.
CO_API bool send (const void *buffer, const uint64_t bytes, const bool isLocked=false)
 Send data using the connection.
void lockSend () const
 Lock the connection, no other thread can send data.
void unlockSend () const
 Unlock the connection.
bool send (const Packet &packet)
 Sends a packaged message using the connection.
bool send (Packet &packet, const std::string &string)
 Sends a packaged message including a string using the connection.
template<typename T >
bool send (Packet &packet, const std::vector< T > &data)
 Sends a packaged message including additional data.
CO_API bool send (Packet &packet, const void *data, const uint64_t size)
 Sends a packaged message including additional data using the connection.
virtual int64_t write (const void *buffer, const uint64_t bytes)=0
 Write data to the connection.
virtual void finish ()

Detailed Description

An interface definition for communication between hosts.

Connections are stream-oriented point-to-point communications. The parameters of a Connection are described in a ConnectionDescription, which is used in listen() and connect(). A Connection has a 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 various low-level communication protocols, e.g., SocketConnection for TCP/IP. An implementation may not implement all the functionality defined in this interface.

The Connection is used reference-counted in co, since it has multiple owners, such as the ConnectionSet and Node.

Definition at line 61 of file connection.h.


Member Enumeration Documentation

The current state of the Connection.

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 64 of file connection.h.


Member Function Documentation

virtual void co::Connection::acceptNB ( ) [inline, virtual]

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.

See also:
acceptSync()

Definition at line 163 of file connection.h.

virtual ConnectionPtr co::Connection::acceptSync ( ) [inline, virtual]

Complete an accept operation.

Returns:
the new connection, 0 on error.

Definition at line 170 of file connection.h.

Add a listener for connection state changes.

virtual bool co::Connection::connect ( ) [inline, virtual]

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.

Definition at line 124 of file connection.h.

static CO_API ConnectionPtr co::Connection::create ( ConnectionDescriptionPtr  description) [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:
descriptionthe connection parameters.
Returns:
the connection.
Returns:
the description for this connection.
virtual Notifier co::Connection::getNotifier ( ) const [pure virtual]
Returns:
the notifier signaling events on the connection.

Implemented in co::BufferConnection.

State co::Connection::getState ( ) const [inline]
Returns:
the State of this connection.

Definition at line 87 of file connection.h.

References _state.

bool co::Connection::isClosed ( ) const [inline]
Returns:
true if the connection is in the closed state.

Definition at line 90 of file connection.h.

References _state, and STATE_CLOSED.

bool co::Connection::isConnected ( ) const [inline]
Returns:
true if the connection is in the connected state.

Definition at line 93 of file connection.h.

References _state, and STATE_CONNECTED.

bool co::Connection::isListening ( ) const [inline]
Returns:
true if the connection is in the listening state.

Definition at line 96 of file connection.h.

References _state, and STATE_LISTENING.

virtual bool co::Connection::listen ( ) [inline, virtual]

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.

Definition at line 135 of file connection.h.

void co::Connection::lockSend ( ) const [inline]

Lock the connection, no other thread can send data.

Definition at line 260 of file connection.h.

References _sendLock.

virtual void co::Connection::readNB ( void *  buffer,
const uint64_t  bytes 
) [pure virtual]

Start a read operation on the connection.

This method is the low-level counterpart to recvNB().

This function returns immediately. The operation's Notifier will signal data availability, upon which readSync() should be 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 
) [pure virtual]

Finish reading data from the connection.

This method is the low-level counterpart to recvSync(). 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 ( void *  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.

Parameters:
bufferthe buffer receiving the data.
bytesthe number of bytes to read.
See also:
recvSync()
CO_API bool co::Connection::recvSync ( void **  buffer,
uint64_t *  bytes,
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 buffer and bytes return value pointers can be 0. This method uses readNB() and readSync() to fill a buffer, potentially by using multiple reads.

Parameters:
bufferreturn value, the buffer pointer passed to recvNB().
bytesreturn value, the number of bytes read.
blockinternal WAR parameter, do not use unless you know exactly why.
Returns:
true if all requested data has been read, false otherwise.

Remove a listener for connection state changes.

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()
bool co::Connection::send ( const Packet packet) [inline]

Sends a packaged message using the connection.

Parameters:
packetthe message packet.
Returns:
true if all data has been read, false if not.

Definition at line 270 of file connection.h.

References send(), and co::Packet::size.

Referenced by send().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

bool co::Connection::send ( Packet packet,
const std::string &  string 
) [inline]

Sends a packaged message including a string using the connection.

The packet has to define a 8-byte-aligned, 8-char string at the end of the packet. When the packet is sent the whole string is appended to the packet, so that the receiver has to do nothing special to receive and use the full packet.

Parameters:
packetthe message packet.
stringthe string.
Returns:
true if all data has been read, false if not.

Definition at line 285 of file connection.h.

References send().

Referenced by send().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

template<typename T >
bool co::Connection::send ( Packet packet,
const std::vector< T > &  data 
)

Sends a packaged message including additional data.

The last item of the packet has to be able to hold one item or eight bytes of the data, whatever is bigger.

Parameters:
packetthe message packet.
datathe vector containing the data.
Returns:
true if all data has been read, false if not.

Definition at line 9 of file connection.h.

CO_API bool co::Connection::send ( Packet packet,
const void *  data,
const uint64_t  size 
)

Sends a packaged message including additional data using the connection.

Parameters:
packetthe message packet.
datathe data.
sizethe data size in bytes.
Returns:
true if all data has been read, false if not.
static CO_API bool co::Connection::send ( const Connections connections,
const Packet packet,
const bool  isLocked = false 
) [static]

Sends a packaged message to multiple connections.

Parameters:
connectionsThe connections.
packetthe message packet.
isLockedtrue if the connection is locked externally.
Returns:
true if the packet was sent successfully to all connections.
static CO_API bool co::Connection::send ( const Connections connections,
Packet packet,
const void *  data,
const uint64_t  size,
const bool  isLocked = false 
) [static]

Sends a packaged message including additional data to multiple connections.

Parameters:
connectionsThe connections.
packetthe message packet.
datathe data.
sizethe data size in bytes.
isLockedtrue if the connection is locked externally.
Returns:
true if the packet was sent successfully to all receivers.
static bool CO_API co::Connection::send ( const Connections connections,
Packet packet,
const void *const *  items,
const uint64_t *  itemSizes,
const size_t  nItems 
) [static]

Sends a packaged message including additional, multiple data items to multiple connections.

Automatically locks each individual connection during send. The data items are appended to the packet individually as a 8-byte size token followed by size bytes data. The packet.size is updated to the size of all data send (packet + sizes + items).

Parameters:
connectionsThe connections.
packetthe message packet.
itemsa pointer array to the data items.
itemSizesan array containing the size of each item.
nItemsthe number of data elements.
Returns:
true if the packet was sent successfully to all receivers.

Set the connection parameter description.

Parameters:
descriptionthe connection parameters.
void co::Connection::unlockSend ( ) const [inline]

Unlock the connection.

Definition at line 262 of file connection.h.

References _sendLock.

virtual int64_t co::Connection::write ( const void *  buffer,
const uint64_t  bytes 
) [pure virtual]

Write data to the connection.

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.


Member Data Documentation

lunchbox::Lock co::Connection::_sendLock [mutable, protected]

The lock used to protect multiple write calls.

Definition at line 395 of file connection.h.

Referenced by lockSend(), and unlockSend().


The documentation for this class was generated from the following files:
Generated on Mon Nov 26 2012 14:41:44 for Collage 0.6.1 by  doxygen 1.7.6.1