proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
selectable.h
Go to the documentation of this file.
1 #ifndef PROTON_SELECTABLE_H
2 #define PROTON_SELECTABLE_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/object.h>
27 #include <proton/event.h>
28 #include <proton/io.h>
29 #include <proton/type_compat.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /**
36  * @file
37  *
38  * The selectable API provides an interface for integration with third
39  * party event loops.
40  *
41  * @defgroup selectable Selectable
42  * @{
43  */
44 
45 /**
46  * An iterator for selectables.
47  */
49 
50 /**
51  * A selectable object provides an interface that can be used to
52  * incorporate proton's I/O into third party event loops.
53  *
54  * Every selectable is associated with exactly one file descriptor.
55  * Selectables may be interested in three kinds of events, read
56  * events, write events, and timer events. A selectable will express
57  * its interest in these events through the ::pn_selectable_capacity(),
58  * ::pn_selectable_pending(), and ::pn_selectable_deadline() calls.
59  *
60  * When a read, write, or timer event occurs, the selectable must be
61  * notified by calling ::pn_selectable_readable(),
62  * ::pn_selectable_writable(), and ::pn_selectable_expired() as
63  * appropriate.
64  *
65  * Once a selectable reaches a terminal state (see
66  * ::pn_selectable_is_terminal()), it will never be interested in
67  * events of any kind. When this occurs it should be removed from the
68  * external event loop and discarded using ::pn_selectable_free().
69  */
71 
72 /**
73  * Construct a new selectables iterator.
74  *
75  * @return a pointer to a new selectables iterator
76  */
77 PN_EXTERN pn_selectables_t *pn_selectables(void);
78 
79 /**
80  * Get the next selectable from an iterator.
81  *
82  * @param[in] selectables a selectable iterator
83  * @return the next selectable from the iterator
84  */
85 PN_EXTERN pn_selectable_t *pn_selectables_next(pn_selectables_t *selectables);
86 
87 /**
88  * Free a selectables iterator.
89  *
90  * @param[in] selectables a selectables iterator (or NULL)
91  */
92 PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables);
93 
95 
102 
104 
105 /**
106  * Get the file descriptor associated with a selectable.
107  *
108  * @param[in] selectable a selectable object
109  * @return the file descriptor associated with the selectable
110  */
112 
113 /**
114  * Set the file descriptor associated with a selectable.
115  *
116  * @param[in] selectable a selectable object
117  * @param[in] fd the file descriptor
118  */
120 
121 /**
122  * Check if a selectable is interested in readable events.
123  *
124  * @param[in] selectable a selectable object
125  * @return true iff the selectable is interested in read events
126  */
128 
129 PN_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading);
130 
131 /**
132  * Check if a selectable is interested in writable events.
133  *
134  * @param[in] selectable a selectable object
135  * @return true iff the selectable is interested in writable events
136  */
138 
139  PN_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing);
140 
141 /**
142  * Get the next deadline for a selectable.
143  *
144  * A selectable with a deadline is interested in being notified when
145  * that deadline expires. Zero indicates there is currently no
146  * deadline.
147  *
148  * @param[in] selectable a selectable object
149  * @return the next deadline or zero
150  */
152 
154 
155 /**
156  * Notify a selectable that the file descriptor is readable.
157  *
158  * @param[in] selectable a selectable object
159  */
161 
162 /**
163  * Notify a selectable that the file descriptor is writable.
164  *
165  * @param[in] selectable a selectable object
166  */
168 
169 /**
170  * Notify a selectable that there is an error on the file descriptor.
171  *
172  * @param[in] selectable a selectable object
173  */
175 
176 /**
177  * Notify a selectable that its deadline has expired.
178  *
179  * @param[in] selectable a selectable object
180  */
182 
183 /**
184  * Check if a selectable is registered.
185  *
186  * This flag is set via ::pn_selectable_set_registered() and can be
187  * used for tracking whether a given selectable has been registerd
188  * with an external event loop.
189  *
190  * @param[in] selectable
191  * @return true if the selectable is registered
192  */
194 
195 /**
196  * Set the registered flag for a selectable.
197  *
198  * See ::pn_selectable_is_registered() for details.
199  *
200  * @param[in] selectable a selectable object
201  * @param[in] registered the registered flag
202  */
203 PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered);
204 
205 /**
206  * Check if a selectable is in the terminal state.
207  *
208  * A selectable that is in the terminal state will never be interested
209  * in being notified of events of any kind ever again. Once a
210  * selectable reaches this state it should be removed from any
211  * external I/O loops and freed in order to reclaim any resources
212  * associated with it.
213  *
214  * @param[in] selectable a selectable object
215  * @return true if the selectable is in the terminal state, false otherwise
216  */
218 
219 /**
220  * Terminate a selectable.
221  *
222  * @param[in] selectable a selectable object
223  */
225 
227 
228 /**
229  * Free a selectable object.
230  *
231  * @param[in] selectable a selectable object (or NULL)
232  */
234 
235 /**
236  * Configure a selectable with a set of callbacks that emit readable,
237  * writable, and expired events into the supplied collector.
238  *
239  * @param[in] selectable a selectable objet
240  */
241 PN_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector);
242 
243 /**
244  * @}
245  */
246 
247 #ifdef __cplusplus
248 }
249 #endif
250 
251 #endif /* selectable.h */
PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables)
Free a selectables iterator.
PN_EXTERN pn_selectable_t * pn_selectables_next(pn_selectables_t *selectables)
Get the next selectable from an iterator.
PN_EXTERN void pn_selectable_terminate(pn_selectable_t *selectable)
Terminate a selectable.
PN_EXTERN pn_socket_t pn_selectable_get_fd(pn_selectable_t *selectable)
Get the file descriptor associated with a selectable.
PN_EXTERN void pn_selectable_on_error(pn_selectable_t *sel, void(*error)(pn_selectable_t *))
PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered)
Set the registered flag for a selectable.
struct pn_record_t pn_record_t
Definition: object.h:46
PN_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing)
PN_EXTERN void pn_selectable_on_expired(pn_selectable_t *sel, void(*expired)(pn_selectable_t *))
struct pn_selectable_t pn_selectable_t
A selectable object provides an interface that can be used to incorporate proton's I/O into third par...
Definition: selectable.h:70
PN_EXTERN void pn_selectable_readable(pn_selectable_t *selectable)
Notify a selectable that the file descriptor is readable.
PN_EXTERN void pn_selectable_error(pn_selectable_t *selectable)
Notify a selectable that there is an error on the file descriptor.
PN_EXTERN pn_selectables_t * pn_selectables(void)
Construct a new selectables iterator.
PN_EXTERN void pn_selectable_free(pn_selectable_t *selectable)
Free a selectable object.
PN_EXTERN void pn_selectable_on_readable(pn_selectable_t *sel, void(*readable)(pn_selectable_t *))
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN bool pn_selectable_is_writing(pn_selectable_t *selectable)
Check if a selectable is interested in writable events.
PN_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector)
Configure a selectable with a set of callbacks that emit readable, writable, and expired events into ...
PN_EXTERN pn_record_t * pn_selectable_attachments(pn_selectable_t *sel)
PN_EXTERN pn_selectable_t * pn_selectable(void)
Event API for the proton Engine.
PN_EXTERN void pn_selectable_on_finalize(pn_selectable_t *sel, void(*finalize)(pn_selectable_t *))
PN_EXTERN void pn_selectable_set_deadline(pn_selectable_t *sel, pn_timestamp_t deadline)
struct pn_iterator_t pn_iterator_t
Definition: object.h:45
PN_EXTERN bool pn_selectable_is_registered(pn_selectable_t *selectable)
Check if a selectable is registered.
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:243
PN_EXTERN bool pn_selectable_is_reading(pn_selectable_t *selectable)
Check if a selectable is interested in readable events.
PN_EXTERN bool pn_selectable_is_terminal(pn_selectable_t *selectable)
Check if a selectable is in the terminal state.
pn_iterator_t pn_selectables_t
An iterator for selectables.
Definition: selectable.h:48
int pn_socket_t
A pn_socket_t provides an abstract handle to an IO stream.
Definition: io.h:58
PN_EXTERN void pn_selectable_expired(pn_selectable_t *selectable)
Notify a selectable that its deadline has expired.
PN_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading)
PN_EXTERN void pn_selectable_on_writable(pn_selectable_t *sel, void(*writable)(pn_selectable_t *))
PN_EXTERN void pn_selectable_set_fd(pn_selectable_t *selectable, pn_socket_t fd)
Set the file descriptor associated with a selectable.
int64_t pn_timestamp_t
Definition: types.h:49
PN_EXTERN void pn_selectable_writable(pn_selectable_t *selectable)
Notify a selectable that the file descriptor is writable.
PN_EXTERN void pn_selectable_on_release(pn_selectable_t *sel, void(*release)(pn_selectable_t *))
PN_EXTERN pn_timestamp_t pn_selectable_get_deadline(pn_selectable_t *selectable)
Get the next deadline for a selectable.
PN_EXTERN void pn_selectable_release(pn_selectable_t *selectable)