Qpid Proton C++  0.12.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Pages
Public Types | Public Member Functions | List of all members
connection_engine Class Referenceabstract

An interface for connection-oriented IO integration. More...

#include <connection_engine.hpp>

Inheritance diagram for connection_engine:
socket_engine

Public Types

enum  io_flag { READ, WRITE }
 Combine these flags with | to indicate read, write, both or neither.
 

Public Member Functions

 connection_engine (handler &, const connection_options &=no_opts)
 Create a connection engine that dispatches to handler.
 
size_t can_read () const
 Return the number of bytes that the engine is currently ready to read.
 
size_t can_write () const
 Return the number of bytes that the engine is currently ready to write.
 
bool process (int io_flags=READ|WRITE)
 Read, write and dispatch events. More...
 
bool process_nothrow (int io_flags=READ|WRITE)
 Non-throwing version of process. More...
 
bool closed () const
 True if the engine is closed, meaning there are no further events to process and close_io has been called. More...
 
std::string error_str () const
 If the engine was closed by an error, return a pointer.
 
class connection connection () const
 Get the AMQP connection associated with this connection_engine.
 
class transport transport () const
 Get the transport associated with this connection_engine.
 
void disconnect ()
 Disconnect the engine.
 

Detailed Description

An interface for connection-oriented IO integration.

A connection_engine manages a single AMQP connection. It is useful for integrating AMQP into an existing IO framework.

The engine provides a simple "bytes-in/bytes-out" interface. Incoming AMQP bytes from any kind of data connection are fed into the engine and processed to dispatch events to a proton::handler. The resulting AMQP output data is available from the engine and can sent back over the connection.

The engine does no IO of its own. It assumes a two-way flow of bytes over some externally-managed "connection". The "connection" could be a socket managed by select, poll, epoll or some other mechanism, or it could be something else such as an RDMA connection, a shared-memory buffer or a Unix pipe.

The application is coded the same way for engine or container: you implement proton::handler. Handlers attached to an engine will receive transport, connection, session, link and message events. They will not receive reactor, selectable or timer events, the engine assumes those are managed externally.

THREAD SAFETY: A single engine instance cannot be called concurrently, but different engine instances can be processed concurrently in separate threads.

Member Function Documentation

bool closed ( ) const

True if the engine is closed, meaning there are no further events to process and close_io has been called.

Call error_str() to get an error description.

Examples:
engine/broker.cpp.
bool process ( int  io_flags = READ|WRITE)

Read, write and dispatch events.

io_flags indicates whether to read, write, both or neither. dispatches all events generated by reading or writing.

Exceptions
proton::closed_errorif closed() is true before calling process()
proton::io_errorif the engine is closed by an error.
Returns
true if process should be called again, i.e. !closed()
bool process_nothrow ( int  io_flags = READ|WRITE)

Non-throwing version of process.

Use closed() and error_str() to check the status of the engine.

Examples:
engine/broker.cpp.

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