proton  0
connection_engine.h
Go to the documentation of this file.
1 #ifndef PROTON_CONNECTION_ENGINE_H
2 #define PROTON_CONNECTION_ENGINE_H
3 
4 /*
5  * Licensed to the Apache Software Foundation (ASF) under one
6  * or more contributor license agreements. See the NOTICE file
7  * distributed with this work for additional information
8  * regarding copyright ownership. The ASF licenses this file
9  * to you under the Apache License, Version 2.0 (the
10  * "License"); you may not use this file except in compliance
11  * with the License. You may obtain a copy of the License at
12  *
13  * http://www.apache.org/licenses/LICENSE-2.0
14  *
15  * Unless required by applicable law or agreed to in writing,
16  * software distributed under the License is distributed on an
17  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18  * KIND, either express or implied. See the License for the
19  * specific language governing permissions and limitations
20  * under the License.
21  */
22 
23 ///@file
24 ///
25 /// **Experimental** The Connection Engine API wraps up the proton engine
26 /// objects associated with a single connection: pn_connection_t, pn_transport_t
27 /// and pn_collector_t. It provides a simple bytes-in/bytes-out interface for IO
28 /// and generates pn_event_t events to be handled by the application.
29 ///
30 /// The connection engine can be fed with raw AMQP bytes from any source, and it
31 /// generates AMQP byte output to be written to any destination. You can use the
32 /// engine to integrate proton AMQP with any IO library, or native IO on any
33 /// platform.
34 ///
35 /// The engine is not thread safe but each engine is independent. Separate
36 /// engines can be used concurrently. For example a multi-threaded application
37 /// can process connections in multiple threads, but serialize work for each
38 /// connection to the corresponding engine.
39 ///
40 /// The engine is designed to be thread and IO neutral so it can be integrated with
41 /// single or multi-threaded code in reactive or proactive IO frameworks.
42 ///
43 /// Summary of use:
44 ///
45 /// - while !pn_connection_engine_finished()
46 /// - Read data from your source into pn_connection_engine_read_buffer()
47 /// - Call pn_connection_engine_read_done() when complete.
48 /// - Write data from pn_connection_engine_write_buffer() to your destination.
49 /// - Call pn_connection_engine_write_done() to indicate how much was written.
50 /// - Call pn_connection_engine_dispatch() to dispatch events until it returns NULL.
51 ///
52 /// Note on error handling: most of the pn_connection_engine_*() functions do
53 /// not return an error code. If a fatal error occurs, the transport error
54 /// condition will be set and the next call to pn_connection_engine_dispatch()
55 /// report it to the handler as a PN_TRANSPORT_ERROR event and return false.
56 ///
57 /// @defgroup connection_engine The Connection Engine
58 /// @ingroup connection_engine
59 /// @{
60 ///
61 
62 #include <proton/condition.h>
63 #include <proton/event.h>
64 #include <proton/import_export.h>
65 #include <proton/types.h>
66 
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 /// A modifiable memory buffer.
72 typedef struct pn_buf_t {
73  char* data; ///< Beginning of the buffered data.
74  size_t size; ///< Number of bytes in the buffer.
75 } pn_buf_t;
76 
77 /// Create a pn_buf
78 PN_EXTERN pn_buf_t pn_buf(char* data, size_t size);
79 
80 /// A read-only memory buffer.
81 typedef struct pn_cbuf_t {
82  const char* data; ///< Beginning of the buffered data.
83  size_t size; ///< Number of bytes in the buffer.
84 } pn_cbuf_t;
85 
86 /// Create a pn_cbuf
87 PN_EXTERN pn_cbuf_t pn_cbuf(const char* data, size_t size);
88 
89 /// A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t.
90 /// Use the pn_connection_engine_*() functions to operate on it.
91 /// It is a plain struct, not a proton object. Use pn_connection_engine_init to set up
92 /// the initial objects and pn_connection_engine_final to release them.
93 ///
94 typedef struct pn_connection_engine_t {
100 
101 /// Initialize a pn_connection_engine_t struct with a new connection, transport
102 /// and collector. Return 0 on success, a proton error code on failure.
104 
105 /// Release the connection, transport and collector associated with engine, set all the pointers
106 /// to NULL. Only call on an engine that was initialized with pn_connection_engine_init
108 
109 /// The engine's read buffer. Read data from your IO source into buf.data, up to
110 /// a max of buf.size. Then call pn_connection_engine_read_done().
111 ///
112 /// buf.size==0 means the engine cannot read presently, calling
113 /// pn_connection_engine_dispatch() may create more buffer space.
114 ///
116 
117 /// Consume the first n bytes of data in pn_connection_engine_read_buffer() and
118 /// update the buffer.
120 
121 /// Close the read side of the transport when no more data is available.
122 /// Note there may still be events for pn_connection_engine_dispatch() or data
123 /// in pn_connection_engine_write_buffer()
125 
126 /// The engine's write buffer. Write data from buf.data to your IO destination,
127 /// up to a max of buf.size. Then call pn_connection_engine_write_done().
128 ///
129 /// buf.size==0 means the engine has nothing to write presently. Calling
130 /// pn_connection_engine_dispatch() may generate more data.
132 
133 /// Call when the first n bytes of pn_connection_engine_write_buffer() have been
134 /// written to IO and can be re-used for new data. Updates the buffer.
136 
137 /// Call when the write side of IO has closed and no more data can be written.
138 /// Note that there may still be events for pn_connection_engine_dispatch() or
139 /// data to read into pn_connection_engine_read_buffer().
141 
142 /// Close both sides of the transport, equivalent to
143 /// pn_connection_engine_read_close(); pn_connection_engine_write_close()
144 ///
145 /// You must still call pn_connection_engine_dispatch() to process final
146 /// events.
147 ///
148 /// To provide transport error information to the handler, set it on
149 /// pn_connection_engine_condition()
150 /// *before* calling pn_connection_engine_disconnected(). This sets
151 /// the error on the pn_transport_t object.
152 ///
153 /// Note this does *not* modify the pn_connection_t, so you can distinguish
154 /// between a connection close error sent by the remote peer (which will set the
155 /// connection condition) and a transport error (which sets the transport
156 /// condition.)
157 ///
159 
160 /// Get the next available event.
161 /// Call in a loop until it returns NULL to dispatch all available events.
162 /// Note this call may modify the read and write buffers.
163 ///
164 /// @return Pointer to the next event, or NULL if there are none available.
165 ///
167 
168 /// Return true if the engine is finished - all data has been written, all
169 /// events have been handled and the transport is closed.
171 
172 /// Get the AMQP connection, owned by the pn_connection_engine_t.
174 
175 /// Get the proton transport, owned by the pn_connection_engine_t.
177 
178 /// Get the condition object for the engine's transport.
179 ///
180 /// Note that IO errors should be set on this, the transport condition, not on
181 /// the pn_connection_t condition. The connection's condition is for errors
182 /// received via the AMQP protocol, the transport condition is for errors in the
183 /// the IO layer such as a socket read or disconnect errors.
184 ///
186 
187 ///@}
188 
189 #ifdef __cplusplus
190 }
191 #endif
192 
193 #endif // PROTON_CONNECTION_ENGINE_H
PN_EXTERN pn_cbuf_t pn_connection_engine_write_buffer(pn_connection_engine_t *)
The engine&#39;s write buffer.
pn_event_t * event
Definition: connection_engine.h:98
PN_EXTERN pn_connection_t * pn_connection_engine_connection(pn_connection_engine_t *)
Get the AMQP connection, owned by the pn_connection_engine_t.
struct pn_cbuf_t pn_cbuf_t
A read-only memory buffer.
PN_EXTERN pn_condition_t * pn_connection_engine_condition(pn_connection_engine_t *)
Get the condition object for the engine&#39;s transport.
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:262
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_eng...
PN_EXTERN pn_buf_t pn_connection_engine_read_buffer(pn_connection_engine_t *)
The engine&#39;s read buffer.
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.
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 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 pn_buf_t pn_buf(char *data, size_t size)
Create a pn_buf.
#define PN_EXTERN
Definition: import_export.h:53
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:250
struct pn_buf_t pn_buf_t
A modifiable memory buffer.
The Condition API for the proton Engine.
char * data
Beginning of the buffered data.
Definition: connection_engine.h:73
PN_EXTERN pn_transport_t * pn_connection_engine_transport(pn_connection_engine_t *)
Get the proton transport, owned by the pn_connection_engine_t.
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...
size_t size
Number of bytes in the buffer.
Definition: connection_engine.h:83
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 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 t...
A modifiable memory buffer.
Definition: connection_engine.h:72
pn_connection_t * connection
Definition: connection_engine.h:95
PN_EXTERN pn_event_t * pn_connection_engine_dispatch(pn_connection_engine_t *)
Get the next available event.
A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t.
Definition: connection_engine.h:94
pn_collector_t * collector
Definition: connection_engine.h:97
Event API for the proton Engine.
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.
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:118
struct pn_condition_t pn_condition_t
An AMQP Condition object.
Definition: condition.h:64
PN_EXTERN pn_cbuf_t pn_cbuf(const char *data, size_t size)
Create a pn_cbuf.
pn_transport_t * transport
Definition: connection_engine.h:96
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...
size_t size
Number of bytes in the buffer.
Definition: connection_engine.h:74
struct pn_event_t pn_event_t
An event provides notification of a state change within the protocol engine&#39;s object model...
Definition: event.h:77
A read-only memory buffer.
Definition: connection_engine.h:81
const char * data
Beginning of the buffered data.
Definition: connection_engine.h:82