Unsettled API - An AMQP driver for a single connection. More...

#include <connection_driver.hpp>

Public Member Functions
	connection_driver ()
	An engine without a container id.

	connection_driver (const std::string &)
	Create a connection driver associated with a container id.

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.

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

void	accept (const connection_options &opts)
	Call configure() with server options.

mutable_buffer	read_buffer ()
	The engine's read buffer.

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

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

const_buffer	write_buffer ()
	The engine's write buffer.

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

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

timestamp	tick (timestamp now)
	Indicate that time has passed.

void	disconnected (const error_condition &=error_condition())
	Inform the engine that the transport been disconnected unexpectedly, without completing the AMQP connection close sequence.

bool	has_events () const
	There are events to be dispatched by dispatch()

bool	dispatch ()
	Dispatch all available events and call the corresponding messaging_handler methods.

proton::connection	connection () const
	Get the AMQP connection associated with this connection_driver.

proton::transport	transport () const
	Get the transport associated with this connection_driver.

proton::container *	container () const
	Get the container associated with this connection_driver, if there is one.

Detailed Description

Unsettled API - 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.

Member Function Documentation

◆ configure()

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.

◆ accept()

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()

◆ read_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.

◆ read_done()

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.

◆ read_close()

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.

◆ write_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.

◆ write_done()

const_buffer 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.

◆ write_close()

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.

◆ tick()

timestamp tick ( timestamp now )

Indicate that time has passed.

Returns: the expiration time of the next unexpired timer. You must arrange to call tick() no later than this expiration time. In practice this will mean calling tick() every time there is anything read or written, and if nothing is read or written then as soon as possible after the returned timestamp (so you will probably need to set a platform specific timeout to know when this occurs).

◆ disconnected()

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.

◆ dispatch()

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:

both read_close() and write_close() have been called, no more IO is possible.
The AMQP connection() is closed AND the write_buffer() is empty.

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

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

proton/io/connection_driver.hpp

Public Member Functions