Qpid Proton C++ API  0.17.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
connection_driver Class Reference

Experimental - An AMQP driver for a single connection. More...

#include <connection_driver.hpp>

Public Member Functions

 connection_driver ()
 An engine that is not associated with a proton::container or proton::event_loop. More...
 
 connection_driver (proton::container &)
 Create a connection driver associated with a proton::container and optional event_loop. More...
 
 connection_driver (proton::container &, event_loop &&loop)
 
void configure (const connection_options &opts=connection_options(), bool server=false)
 Configure a connection by applying exactly the options in opts (including proton::messaging_handler) Does not apply any default options, to apply container defaults use connect() or accept() instead. More...
 
void connect (const connection_options &opts)
 Call configure() with client options and call connection::open() Options applied: container::id(), container::client_connection_options(), opts. More...
 
void accept (const connection_options &opts)
 Call configure() with server options. More...
 
mutable_buffer read_buffer ()
 The engine's read buffer. More...
 
void read_done (size_t n)
 Indicate that the first n bytes of read_buffer() have valid data. More...
 
void read_close ()
 Indicate that the read side of the transport is closed and no more data will be read. More...
 
const_buffer write_buffer ()
 The engine's write buffer. More...
 
void write_done (size_t n)
 Indicate that the first n bytes of write_buffer() have been written successfully. More...
 
void write_close ()
 Indicate that the write side of the transport has closed and no more data can be written. More...
 
void disconnected (const error_condition &=error_condition())
 Inform the engine that the transport been disconnected unexpectedly, without completing the AMQP connection close sequence. More...
 
bool dispatch ()
 Dispatch all available events and call the corresponding messaging_handler methods. More...
 
proton::connection connection () const
 Get the AMQP connection associated with this connection_driver. More...
 
proton::transport transport () const
 Get the transport associated with this connection_driver.
 
proton::containercontainer () const
 Get the container associated with this connection_driver, if there is one.
 

Detailed Description

Experimental - An AMQP driver for a single connection.

io::connection_driver manages a single proton::connection and dispatches events to a proton::messaging_handler. It does no IO of its own, but allows you to integrate AMQP protocol handling into any IO or concurrency framework.

The application is coded the same way as for the proton::container. The application implements a proton::messaging_handler to respond to transport, connection, session, link, and message events. With a little care, the same handler classes can be used for both container and connection_driver. the broker.cpp example illustrates this.

You need to write the IO code to read AMQP data to the read_buffer(). The engine parses the AMQP frames. dispatch() calls the appropriate functions on the applications proton::messaging_handler. You write output data from the engine's write_buffer() to your IO.

The engine is not safe for concurrent use, but you can process different engines concurrently. A common pattern for high-performance servers is to serialize read/write activity per connection and dispatch in a fixed-size thread pool.

The engine is designed to work with a classic reactor (e.g., select, poll, epoll) or an async-request driven proactor (e.g., windows completion ports, boost.asio, libuv).

The engine never throws exceptions.

Examples:
mt/epoll_container.cpp.

Constructor & Destructor Documentation

An engine that is not associated with a proton::container or proton::event_loop.

Accessing the container or event_loop for this connection in a proton::messaging_handler will throw a proton::error exception.

Create a connection driver associated with a proton::container and optional event_loop.

If the event_loop is not provided attempts to use it will throw proton::error.

Takes ownership of the event_loop. Note the proton::connection created by this connection_driver can outlive the connection_driver itself if the user pins it in memory using the proton::thread_safe<> template. The event_loop is deleted when, and only when, the proton::connection is.

Member Function Documentation

void accept ( const connection_options opts)

Call configure() with server options.

Options applied: container::id(), container::server_connection_options(), opts.

Note this does not call connection::open(). If there is a messaging_handler in the composed options it will receive messaging_handler::on_connection_open() and can respond with connection::open() or connection::close()

void configure ( const connection_options opts = connection_options(),
bool  server = false 
)

Configure a connection by applying exactly the options in opts (including proton::messaging_handler) Does not apply any default options, to apply container defaults use connect() or accept() instead.

If server==true, configure a server connection.

void connect ( const connection_options opts)

Call configure() with client options and call connection::open() Options applied: container::id(), container::client_connection_options(), opts.

Get the AMQP connection associated with this connection_driver.

The event_loop is availabe via proton::thread_safe<connection>(connection())

void disconnected ( const error_condition = error_condition())

Inform the engine that the transport been disconnected unexpectedly, without completing the AMQP connection close sequence.

This calls read_close(), write_close(), sets the transport().error() and queues an on_transport_error event. You must call dispatch() one more time to dispatch the messaging_handler::on_transport_error() call and other final events.

Note this does not close the connection() so that a proton::messaging_handler can distinguish between a connection close error sent by the remote peer and a transport failure.

bool dispatch ( )

Dispatch all available events and call the corresponding messaging_handler methods.

Returns true if the engine is still active, false if it is finished and can be destroyed. The engine is finished when all events are dispatched and one of the following is true:

May modify the read_buffer() and/or the write_buffer().

mutable_buffer read_buffer ( )

The engine's read buffer.

Read data into this buffer then call read_done() when complete. Returns mutable_buffer(0, 0) if the engine cannot currently read data. Calling dispatch() may open up more buffer space.

void read_close ( )

Indicate that the read side of the transport is closed and no more data will be read.

Note that there may still be events to dispatch() or data to write.

void read_done ( size_t  n)

Indicate that the first n bytes of read_buffer() have valid data.

This changes the buffer, call read_buffer() to get the updated buffer.

const_buffer write_buffer ( )

The engine's write buffer.

Write data from this buffer then call write_done() Returns const_buffer(0, 0) if the engine has nothing to write. Calling dispatch() may generate more data in the write buffer.

void write_close ( )

Indicate that the write side of the transport has closed and no more data can be written.

Note that there may still be events to dispatch() or data to read.

void write_done ( size_t  n)

Indicate that the first n bytes of write_buffer() have been written successfully.

This changes the buffer, call write_buffer() to get the updated buffer.


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