/builddir/build/BUILD/qpid-proton-0.14.0/proton-c/include/proton/connection_engine.h File Reference

Experimental** The Connection Engine API wraps up the proton engine objects associated with a single connection: pn_connection_t, pn_transport_t and pn_collector_t. More...

#include <proton/condition.h>
#include <proton/event.h>
#include <proton/import_export.h>
#include <proton/types.h>

Go to the source code of this file.

Data Structures

struct  pn_buf_t
 A modifiable memory buffer. More...
struct  pn_cbuf_t
 A read-only memory buffer. More...
struct  pn_connection_engine_t
 A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t. More...

Functions

PN_EXTERN pn_buf_t pn_buf (char *data, size_t size)
 Create a pn_buf.
PN_EXTERN pn_cbuf_t pn_cbuf (const char *data, size_t size)
 Create a pn_cbuf.
PN_EXTERN int pn_connection_engine_init (pn_connection_engine_t *engine)
 Initialize a pn_connection_engine_t struct with a new connection, transport and collector.
PN_EXTERN void pn_connection_engine_final (pn_connection_engine_t *engine)
 Release the connection, transport and collector associated with engine, set all the pointers to NULL.
PN_EXTERN pn_buf_t pn_connection_engine_read_buffer (pn_connection_engine_t *)
 The engine's read buffer.
PN_EXTERN void pn_connection_engine_read_done (pn_connection_engine_t *, size_t n)
 Consume the first n bytes of data in pn_connection_engine_read_buffer() and update the buffer.
PN_EXTERN void pn_connection_engine_read_close (pn_connection_engine_t *)
 Close the read side of the transport when no more data is available.
PN_EXTERN pn_cbuf_t pn_connection_engine_write_buffer (pn_connection_engine_t *)
 The engine's write buffer.
PN_EXTERN void pn_connection_engine_write_done (pn_connection_engine_t *, size_t n)
 Call when the first n bytes of pn_connection_engine_write_buffer() have been written to IO and can be re-used for new data.
PN_EXTERN void pn_connection_engine_write_close (pn_connection_engine_t *)
 Call when the write side of IO has closed and no more data can be written.
PN_EXTERN void pn_connection_engine_disconnected (pn_connection_engine_t *)
 Close both sides of the transport, equivalent to pn_connection_engine_read_close(); pn_connection_engine_write_close().
PN_EXTERN pn_event_tpn_connection_engine_dispatch (pn_connection_engine_t *)
 Get the next available event.
PN_EXTERN bool pn_connection_engine_finished (pn_connection_engine_t *)
 Return true if the engine is finished - all data has been written, all events have been handled and the transport is closed.
PN_EXTERN pn_connection_tpn_connection_engine_connection (pn_connection_engine_t *)
 Get the AMQP connection, owned by the pn_connection_engine_t.
PN_EXTERN pn_transport_tpn_connection_engine_transport (pn_connection_engine_t *)
 Get the proton transport, owned by the pn_connection_engine_t.
PN_EXTERN pn_condition_tpn_connection_engine_condition (pn_connection_engine_t *)
 Get the condition object for the engine's transport.

Detailed Description

Experimental** The Connection Engine API wraps up the proton engine objects associated with a single connection: pn_connection_t, pn_transport_t and pn_collector_t.

It provides a simple bytes-in/bytes-out interface for IO and generates pn_event_t events to be handled by the application.

The connection engine can be fed with raw AMQP bytes from any source, and it generates AMQP byte output to be written to any destination. You can use the engine to integrate proton AMQP with any IO library, or native IO on any platform.

The engine is not thread safe but each engine is independent. Separate engines can be used concurrently. For example a multi-threaded application can process connections in multiple threads, but serialize work for each connection to the corresponding engine.

The engine is designed to be thread and IO neutral so it can be integrated with single or multi-threaded code in reactive or proactive IO frameworks.

Summary of use:

Note on error handling: most of the pn_connection_engine_*() functions do not return an error code. If a fatal error occurs, the transport error condition will be set and the next call to pn_connection_engine_dispatch() report it to the handler as a PN_TRANSPORT_ERROR event and return false.

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 23 Sep 2016 for proton by  doxygen 1.6.1