proton  0
types.h
Go to the documentation of this file.
1 #ifndef PROTON_TYPES_H
2 #define PROTON_TYPES_H 1
3 
4 
5 /*
6  *
7  * Licensed to the Apache Software Foundation (ASF) under one
8  * or more contributor license agreements. See the NOTICE file
9  * distributed with this work for additional information
10  * regarding copyright ownership. The ASF licenses this file
11  * to you under the Apache License, Version 2.0 (the
12  * "License"); you may not use this file except in compliance
13  * with the License. You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing,
18  * software distributed under the License is distributed on an
19  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20  * KIND, either express or implied. See the License for the
21  * specific language governing permissions and limitations
22  * under the License.
23  *
24  */
25 
26 #include <proton/import_export.h>
27 #include <stddef.h>
28 #include <proton/type_compat.h>
29 
30 /**
31  * @file
32  *
33  * @defgroup types Types
34  * @{
35  */
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 /**
42  * @defgroup primitives Primitive Types
43  * @{
44  */
45 
46 typedef int32_t pn_sequence_t;
47 typedef uint32_t pn_millis_t;
48 #define PN_MILLIS_MAX (~0U)
49 typedef uint32_t pn_seconds_t;
50 
51 typedef int64_t pn_timestamp_t;
52 
53 /** Return a timestamp for the time now. */
54 PN_EXTERN pn_timestamp_t pn_timestamp_now(void);
55 
56 
57 typedef uint32_t pn_char_t;
58 typedef uint32_t pn_decimal32_t;
59 typedef uint64_t pn_decimal64_t;
60 typedef struct {
61  char bytes[16];
63 typedef struct {
64  char bytes[16];
65 } pn_uuid_t;
66 
67 typedef struct {
68  size_t size;
69  const char *start;
70 } pn_bytes_t;
71 
72 PN_EXTERN pn_bytes_t pn_bytes(size_t size, const char *start);
73 
74 /** @}
75  */
76 
77 /**
78  * @defgroup abstract Abstract Types
79  * @{
80  */
81 
82 /**
83  * Holds the state flags for an AMQP endpoint.
84  *
85  * A pn_state_t is an integral value with flags that encode both the
86  * local and remote state of an AMQP Endpoint (@link pn_connection_t
87  * Connection @endlink, @link pn_session_t Session @endlink, or @link
88  * pn_link_t Link @endlink). The local portion of the state may be
89  * accessed using ::PN_LOCAL_MASK, and the remote portion may be
90  * accessed using ::PN_REMOTE_MASK. Individual bits may be accessed
91  * using ::PN_LOCAL_UNINIT, ::PN_LOCAL_ACTIVE, ::PN_LOCAL_CLOSED, and
92  * ::PN_REMOTE_UNINIT, ::PN_REMOTE_ACTIVE, ::PN_REMOTE_CLOSED.
93  *
94  * Every AMQP endpoint (@link pn_connection_t Connection @endlink,
95  * @link pn_session_t Session @endlink, or @link pn_link_t Link
96  * @endlink) starts out in an uninitialized state and then proceeds
97  * linearly to an active and then closed state. This lifecycle occurs
98  * at both endpoints involved, and so the state model for an endpoint
99  * includes not only the known local state, but also the last known
100  * state of the remote endpoint.
101  *
102  * @ingroup connection
103  */
104 typedef int pn_state_t;
105 
106 /**
107  * An AMQP Connection object.
108  *
109  * A pn_connection_t object encapsulates all of the endpoint state
110  * associated with an AMQP Connection. A pn_connection_t object
111  * contains zero or more ::pn_session_t objects, which in turn contain
112  * zero or more ::pn_link_t objects. Each ::pn_link_t object contains
113  * an ordered sequence of ::pn_delivery_t objects. A link is either a
114  * @link sender Sender @endlink, or a @link receiver Receiver
115  * @endlink, but never both.
116  *
117  * @ingroup connection
118  */
119 typedef struct pn_connection_t pn_connection_t;
120 
121 /**
122  * An AMQP Session object.
123  *
124  * A pn_session_t object encapsulates all of the endpoint state
125  * associated with an AMQP Session. A pn_session_t object contains
126  * zero or more ::pn_link_t objects.
127  *
128  * @ingroup session
129  */
130 typedef struct pn_session_t pn_session_t;
131 
132 /**
133  * An AMQP Link object.
134  *
135  * A pn_link_t object encapsulates all of the endpoint state
136  * associated with an AMQP Link. A pn_link_t object contains an
137  * ordered sequence of ::pn_delivery_t objects representing in-flight
138  * deliveries. A pn_link_t may be either a @link sender Sender
139  * @endlink, or a @link receiver Receiver @endlink, but never both.
140  *
141  * A pn_link_t object maintains a pointer to the *current* delivery
142  * within the ordered sequence of deliveries contained by the link
143  * (See ::pn_link_current). The *current* delivery is the target of a
144  * number of operations associated with the link, such as sending
145  * (::pn_link_send) and receiving (::pn_link_recv) message data.
146  *
147  * @ingroup link
148  */
149 typedef struct pn_link_t pn_link_t;
150 
151 /**
152  * An AMQP Delivery object.
153  *
154  * A pn_delivery_t object encapsulates all of the endpoint state
155  * associated with an AMQP Delivery. Every delivery exists within the
156  * context of a ::pn_link_t object.
157  *
158  * The AMQP model for settlement is based on the lifecycle of a
159  * delivery at an endpoint. At each end of a link, a delivery is
160  * created, it exists for some period of time, and finally it is
161  * forgotten, aka settled. Note that because this lifecycle happens
162  * independently at both the sender and the receiver, there are
163  * actually four events of interest in the combined lifecycle of a
164  * given delivery:
165  *
166  * - created at sender
167  * - created at receiver
168  * - settled at sender
169  * - settled at receiver
170  *
171  * Because the sender and receiver are operating concurrently, these
172  * events can occur in a variety of different orders, and the order of
173  * these events impacts the types of failures that may occur when
174  * transferring a delivery. Eliminating scenarios where the receiver
175  * creates the delivery first, we have the following possible
176  * sequences of interest:
177  *
178  * Sender presettles (aka at-most-once):
179  * -------------------------------------
180  *
181  * 1. created at sender
182  * 2. settled at sender
183  * 3. created at receiver
184  * 4. settled at receiver
185  *
186  * In this configuration the sender settles (i.e. forgets about) the
187  * delivery before it even reaches the receiver, and if anything
188  * should happen to the delivery in-flight, there is no way to
189  * recover, hence the "at most once" semantics.
190  *
191  * Receiver settles first (aka at-least-once):
192  * -------------------------------------------
193  *
194  * 1. created at sender
195  * 2. created at receiver
196  * 3. settled at receiver
197  * 4. settled at sender
198  *
199  * In this configuration the receiver settles the delivery first, and
200  * the sender settles once it sees the receiver has settled. Should
201  * anything happen to the delivery in-flight, the sender can resend,
202  * however the receiver may have already forgotten the delivery and so
203  * it could interpret the resend as a new delivery, hence the "at
204  * least once" semantics.
205  *
206  * Receiver settles second (aka exactly-once):
207  * -------------------------------------------
208  *
209  * 1. created at sender
210  * 2. created at receiver
211  * 3. settled at sender
212  * 4. settled at receiver
213  *
214  * In this configuration the receiver settles only once it has seen
215  * that the sender has settled. This provides the sender the option to
216  * retransmit, and the receiver has the option to recognize (and
217  * discard) duplicates, allowing for exactly once semantics.
218  *
219  * Note that in the last scenario the sender needs some way to know
220  * when it is safe to settle. This is where delivery state comes in.
221  * In addition to these lifecycle related events surrounding
222  * deliveries there is also the notion of a delivery state that can
223  * change over the lifetime of a delivery, e.g. it might start out as
224  * nothing, transition to ::PN_RECEIVED and then transition to
225  * ::PN_ACCEPTED. In the first two scenarios the delivery state isn't
226  * required, however in final scenario the sender would typically
227  * trigger settlement based on seeing the delivery state transition to
228  * a terminal state like ::PN_ACCEPTED or ::PN_REJECTED.
229  *
230  * In practice settlement is controlled by application policy, so
231  * there may well be more options here, e.g. a sender might not settle
232  * strictly based on what has happened at the receiver, it might also
233  * choose to impose some time limit and settle after that period has
234  * expired, or it could simply have a sliding window of the last N
235  * deliveries and settle the oldest whenever a new one comes along.
236  *
237  * @ingroup delivery
238  */
239 typedef struct pn_delivery_t pn_delivery_t;
240 
241 /**
242  * An event collector.
243  *
244  * A pn_collector_t may be used to register interest in being notified
245  * of high level events that can occur to the various objects
246  * representing AMQP endpoint state. See ::pn_event_t for more
247  * details.
248  *
249  * @ingroup event
250  */
251 typedef struct pn_collector_t pn_collector_t;
252 
253 /**
254  * An AMQP Transport object.
255  *
256  * A pn_transport_t encapsulates the transport related state of all
257  * AMQP endpoint objects associated with a physical network connection
258  * at a given point in time.
259  *
260  * @ingroup transport
261  */
263 typedef struct pn_transport_t pn_transport_t;
264 
265 /**
266  * An event handler
267  *
268  * A pn_handler_t is target of ::pn_event_t dispatched by the ::pn_reactor_t
269  *
270  * @ingroup reactor
271  */
272 typedef struct pn_handler_t pn_handler_t;
273 
274 /** @}
275  */
276 #ifdef __cplusplus
277 }
278 #endif
279 
280 /** @}
281  */
282 
283 #endif /* types.h */
const char * start
Definition: types.h:69
uint32_t pn_millis_t
Definition: types.h:47
struct pn_transport_t pn_transport_t
An AMQP Transport object.
Definition: types.h:262
uint32_t pn_seconds_t
Definition: types.h:49
PN_EXTERN pn_timestamp_t pn_timestamp_now(void)
Return a timestamp for the time now.
Definition: types.h:63
uint32_t pn_char_t
Definition: types.h:57
#define PN_EXTERN
Definition: import_export.h:53
Definition: types.h:67
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:250
struct pn_session_t pn_session_t
An AMQP Session object.
Definition: types.h:129
int32_t pn_sequence_t
Definition: types.h:46
struct pn_handler_t pn_handler_t
An event handler.
Definition: types.h:271
struct pn_delivery_t pn_delivery_t
An AMQP Delivery object.
Definition: types.h:238
uint32_t pn_decimal32_t
Definition: types.h:58
int64_t pn_timestamp_t
Definition: types.h:51
struct pn_connection_t pn_connection_t
An AMQP Connection object.
Definition: types.h:118
uint64_t pn_decimal64_t
Definition: types.h:59
Definition: types.h:60
size_t size
Definition: types.h:68
int pn_state_t
Holds the state flags for an AMQP endpoint.
Definition: types.h:103
PN_EXTERN pn_bytes_t pn_bytes(size_t size, const char *start)