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

## Typedefs

typedef struct pn_buf_t | pn_buf_t
| A modifiable memory buffer. More...
typedef struct pn_cbuf_t | pn_cbuf_t
| A read-only memory buffer. More...
typedef struct pn_connection_engine_t | 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. More...
PN_EXTERN pn_cbuf_t | pn_cbuf (const char *data, size_t size)
| Create a pn_cbuf. More...
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. More...
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. More...
PN_EXTERN pn_buf_t | pn_connection_engine_read_buffer (pn_connection_engine_t *)
| The engine's read buffer. More...
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. More...
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. More...
PN_EXTERN pn_cbuf_t | pn_connection_engine_write_buffer (pn_connection_engine_t *)
| The engine's write buffer. More...
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. More...
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. More...
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() More...
PN_EXTERN pn_event_t * | pn_connection_engine_dispatch (pn_connection_engine_t *)
| Get the next available event. More...
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. More...
PN_EXTERN pn_connection_t * | pn_connection_engine_connection (pn_connection_engine_t *)
| Get the AMQP connection, owned by the pn_connection_engine_t. More...
PN_EXTERN pn_transport_t * | pn_connection_engine_transport (pn_connection_engine_t *)
| Get the proton transport, owned by the pn_connection_engine_t. More...
PN_EXTERN pn_condition_t * | pn_connection_engine_condition (pn_connection_engine_t *)
| Get the condition object for the engine's transport. More...

## 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:

- while !pn_connection_engine_finished()
  - Read data from your source into pn_connection_engine_read_buffer()
  - Call pn_connection_engine_read_done() when complete.
  - Write data from pn_connection_engine_write_buffer() to your destination.
  - Call pn_connection_engine_write_done() to indicate how much was written.
  - Call pn_connection_engine_dispatch() to dispatch events until it returns NULL.

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.