proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups 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.
57  *
58  * When a read, write, or timer event occurs, the selectable must be
59  * notified by calling ::pn_selectable_readable(),
60  * ::pn_selectable_writable(), and ::pn_selectable_expired() as
61  * appropriate.
62  *
63  * Once a selectable reaches a terminal state (see
64  * ::pn_selectable_is_terminal()), it will never be interested in
65  * events of any kind. When this occurs it should be removed from the
66  * external event loop and discarded using ::pn_selectable_free().
67  */
69 
70 /**
71  * Construct a new selectables iterator.
72  *
73  * @return a pointer to a new selectables iterator
74  */
75 PN_EXTERN pn_selectables_t *pn_selectables(void);
76 
77 /**
78  * Get the next selectable from an iterator.
79  *
80  * @param[in] selectables a selectable iterator
81  * @return the next selectable from the iterator
82  */
83 PN_EXTERN pn_selectable_t *pn_selectables_next(pn_selectables_t *selectables);
84 
85 /**
86  * Free a selectables iterator.
87  *
88  * @param[in] selectables a selectables iterator (or NULL)
89  */
90 PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables);
91 
93 
100 
102 
103 /**
104  * Get the file descriptor associated with a selectable.
105  *
106  * @param[in] selectable a selectable object
107  * @return the file descriptor associated with the selectable
108  */
110 
111 /**
112  * Set the file descriptor associated with a selectable.
113  *
114  * @param[in] selectable a selectable object
115  * @param[in] fd the file descriptor
116  */
118 
119 /**
120  * Check if a selectable is interested in readable events.
121  *
122  * @param[in] selectable a selectable object
123  * @return true iff the selectable is interested in read events
124  */
126 
127 PN_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading);
128 
129 /**
130  * Check if a selectable is interested in writable events.
131  *
132  * @param[in] selectable a selectable object
133  * @return true iff the selectable is interested in writable events
134  */
136 
137  PN_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing);
138 
139 /**
140  * Get the next deadline for a selectable.
141  *
142  * A selectable with a deadline is interested in being notified when
143  * that deadline expires. Zero indicates there is currently no
144  * deadline.
145  *
146  * @param[in] selectable a selectable object
147  * @return the next deadline or zero
148  */
150 
152 
153 /**
154  * Notify a selectable that the file descriptor is readable.
155  *
156  * @param[in] selectable a selectable object
157  */
159 
160 /**
161  * Notify a selectable that the file descriptor is writable.
162  *
163  * @param[in] selectable a selectable object
164  */
166 
167 /**
168  * Notify a selectable that there is an error on the file descriptor.
169  *
170  * @param[in] selectable a selectable object
171  */
173 
174 /**
175  * Notify a selectable that its deadline has expired.
176  *
177  * @param[in] selectable a selectable object
178  */
180 
181 /**
182  * Check if a selectable is registered.
183  *
184  * This flag is set via ::pn_selectable_set_registered() and can be
185  * used for tracking whether a given selectable has been registerd
186  * with an external event loop.
187  *
188  * @param[in] selectable
189  * @return true if the selectable is registered
190  */
192 
193 /**
194  * Set the registered flag for a selectable.
195  *
196  * See ::pn_selectable_is_registered() for details.
197  *
198  * @param[in] selectable a selectable object
199  * @param[in] registered the registered flag
200  */
201 PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered);
202 
203 /**
204  * Check if a selectable is in the terminal state.
205  *
206  * A selectable that is in the terminal state will never be interested
207  * in being notified of events of any kind ever again. Once a
208  * selectable reaches this state it should be removed from any
209  * external I/O loops and freed in order to reclaim any resources
210  * associated with it.
211  *
212  * @param[in] selectable a selectable object
213  * @return true if the selectable is in the terminal state, false otherwise
214  */
216 
217 /**
218  * Terminate a selectable.
219  *
220  * @param[in] selectable a selectable object
221  */
223 
225 
226 /**
227  * Free a selectable object.
228  *
229  * @param[in] selectable a selectable object (or NULL)
230  */
232 
233 /**
234  * Configure a selectable with a set of callbacks that emit readable,
235  * writable, and expired events into the supplied collector.
236  *
237  * @param[in] selectable a selectable objet
238  * @param[in] collector a collector object
239  */
240 PN_EXTERN void pn_selectable_collect(pn_selectable_t *selectable, pn_collector_t *collector);
241 
242 /**
243  * @}
244  */
245 
246 #ifdef __cplusplus
247 }
248 #endif
249 
250 #endif /* selectable.h */
PN_EXTERN pn_socket_t pn_selectable_get_fd(pn_selectable_t *selectable)
Get the file descriptor associated with a selectable.
PN_EXTERN bool pn_selectable_is_terminal(pn_selectable_t *selectable)
Check if a selectable is in the terminal state.
PN_EXTERN void pn_selectable_error(pn_selectable_t *selectable)
Notify a selectable that there is an error on the file descriptor.
PN_EXTERN bool pn_selectable_is_registered(pn_selectable_t *selectable)
Check if a selectable is registered.
PN_EXTERN pn_selectable_t * pn_selectable(void)
PN_EXTERN pn_selectable_t * pn_selectables_next(pn_selectables_t *selectables)
Get the next selectable from an iterator.
struct pn_record_t pn_record_t
Definition: object.h:46
PN_EXTERN void pn_selectable_set_deadline(pn_selectable_t *sel, pn_timestamp_t deadline)
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_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 void pn_selectable_free(pn_selectable_t *selectable)
Free a selectable object.
PN_EXTERN void pn_selectable_expired(pn_selectable_t *selectable)
Notify a selectable that its deadline has expired.
PN_EXTERN void pn_selectable_terminate(pn_selectable_t *selectable)
Terminate a selectable.
PN_EXTERN void pn_selectable_set_reading(pn_selectable_t *sel, bool reading)
PN_EXTERN pn_record_t * pn_selectable_attachments(pn_selectable_t *sel)
#define PN_EXTERN
Definition: import_export.h:53
PN_EXTERN pn_selectables_t * pn_selectables(void)
Construct a new selectables iterator.
struct pn_collector_t pn_collector_t
An event collector.
Definition: types.h:250
PN_EXTERN void pn_selectable_set_writing(pn_selectable_t *sel, bool writing)
PN_EXTERN void pn_selectable_on_finalize(pn_selectable_t *sel, void(*finalize)(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.
PN_EXTERN void pn_selectable_on_readable(pn_selectable_t *sel, void(*readable)(pn_selectable_t *))
PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered)
Set the registered flag for a selectable.
PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables)
Free a selectables iterator.
int pn_socket_t
A pn_socket_t provides an abstract handle to an IO stream.
Definition: io.h:58
PN_EXTERN bool pn_selectable_is_reading(pn_selectable_t *selectable)
Check if a selectable is interested in readable events.
PN_EXTERN void pn_selectable_on_expired(pn_selectable_t *sel, void(*expired)(pn_selectable_t *))
PN_EXTERN void pn_selectable_release(pn_selectable_t *selectable)
PN_EXTERN void pn_selectable_writable(pn_selectable_t *selectable)
Notify a selectable that the file descriptor is writable.
Event API for the proton Engine.
int64_t pn_timestamp_t
Definition: types.h:51
PN_EXTERN void pn_selectable_readable(pn_selectable_t *selectable)
Notify a selectable that the file descriptor is readable.
PN_EXTERN void pn_selectable_on_release(pn_selectable_t *sel, void(*release)(pn_selectable_t *))
pn_iterator_t pn_selectables_t
An iterator for selectables.
Definition: selectable.h:48
PN_EXTERN void pn_selectable_on_writable(pn_selectable_t *sel, void(*writable)(pn_selectable_t *))
PN_EXTERN bool pn_selectable_is_writing(pn_selectable_t *selectable)
Check if a selectable is interested in writable events.
struct pn_iterator_t pn_iterator_t
Definition: object.h:45
struct pn_selectable_t pn_selectable_t
A selectable object provides an interface that can be used to incorporate proton&#39;s I/O into third par...
Definition: selectable.h:68
PN_EXTERN void pn_selectable_on_error(pn_selectable_t *sel, void(*error)(pn_selectable_t *))