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/io.h>
28 #include <proton/type_compat.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * @file
36  *
37  * The selectable API provides an interface for integration with third
38  * party event loops.
39  *
40  * @defgroup selectable Selectable
41  * @{
42  */
43 
44 /**
45  * An iterator for selectables.
46  */
48 
49 /**
50  * A selectable object provides an interface that can be used to
51  * incorporate proton's I/O into third party event loops.
52  *
53  * Every selectable is associated with exactly one file descriptor.
54  * Selectables may be interested in three kinds of events, read
55  * events, write events, and timer events. A selectable will express
56  * its interest in these events through the ::pn_selectable_capacity(),
57  * ::pn_selectable_pending(), and ::pn_selectable_deadline() calls.
58  *
59  * When a read, write, or timer event occurs, the selectable must be
60  * notified by calling ::pn_selectable_readable(),
61  * ::pn_selectable_writable(), and ::pn_selectable_expired() as
62  * appropriate.
63  *
64  * Once a selectable reaches a terminal state (see
65  * ::pn_selectable_is_terminal()), it will never be interested in
66  * events of any kind. When this occurs it should be removed from the
67  * external event loop and discarded using ::pn_selectable_free().
68  */
70 
71 /**
72  * Construct a new selectables iterator.
73  *
74  * @return a pointer to a new selectables iterator
75  */
76 PN_EXTERN pn_selectables_t *pn_selectables(void);
77 
78 /**
79  * Get the next selectable from an iterator.
80  *
81  * @param[in] selectables a selectable iterator
82  * @return the next selectable from the iterator
83  */
84 PN_EXTERN pn_selectable_t *pn_selectables_next(pn_selectables_t *selectables);
85 
86 /**
87  * Free a selectables iterator.
88  *
89  * @param[in] selectables a selectables iterator (or NULL)
90  */
91 PN_EXTERN void pn_selectables_free(pn_selectables_t *selectables);
92 
93 /**
94  * Get the file descriptor associated with a selectable.
95  *
96  * @param[in] selectable a selectable object
97  * @return the file descriptor associated with the selectable
98  */
100 
101 /**
102  * Get the capacity of a selectable.
103  *
104  * A selectable with a positive capacity is interested in being
105  * notified of read events. A negative capacity indicates that the
106  * selectable will never be interested in read events ever again.
107  *
108  * @param[in] selectable a selectable object
109  * @return the selectables capacity
110  */
112 
113 /**
114  * Get the number of bytes pending for a selectable.
115  *
116  * A selectable with pending bytes is interested in being notified of
117  * write events. If this value is negative then the selectable will
118  * never be interested in write events ever again.
119  *
120  * @param[in] selectable a selectable object
121  * @return the number of bytes pending for the selectable
122  */
123 PN_EXTERN ssize_t pn_selectable_pending(pn_selectable_t *selectable);
124 
125 /**
126  * Get the next deadline for a selectable.
127  *
128  * A selectable with a deadline is interested in being notified when
129  * that deadline expires. Zero indicates there is currently no
130  * deadline.
131  *
132  * @param[in] selectable a selectable object
133  * @return the next deadline or zero
134  */
136 
137 /**
138  * Notify a selectable that the file descriptor is readable.
139  *
140  * @param[in] selectable a selectable object
141  */
143 
144 /**
145  * Notify a selectable that the file descriptor is writable.
146  *
147  * @param[in] selectable a selectable object
148  */
150 
151 /**
152  * Notify a selectable that its deadline has expired.
153  *
154  * @param[in] selectable a selectable object
155  */
157 
158 /**
159  * Check if a selectable is registered.
160  *
161  * This flag is set via ::pn_selectable_set_registered() and can be
162  * used for tracking whether a given selectable has been registerd
163  * with an external event loop.
164  *
165  * @param[in] selectable
166  * @return true if the selectable is registered
167  */
169 
170 /**
171  * Set the registered flag for a selectable.
172  *
173  * See ::pn_selectable_is_registered() for details.
174  *
175  * @param[in] selectable a selectable object
176  * @param[in] registered the registered flag
177  */
178 PN_EXTERN void pn_selectable_set_registered(pn_selectable_t *selectable, bool registered);
179 
180 /**
181  * Check if a selectable is in the terminal state.
182  *
183  * A selectable that is in the terminal state will never be interested
184  * in being notified of events of any kind ever again. Once a
185  * selectable reaches this state it should be removed from any
186  * external I/O loops and freed in order to reclaim any resources
187  * associated with it.
188  *
189  * @param[in] selectable a selectable object
190  * @return true if the selectable is in the terminal state, false otherwise
191  */
193 
194 /**
195  * Free a selectable object.
196  *
197  * @param[in] selectable a selectable object (or NULL)
198  */
200 
201 /**
202  * @}
203  */
204 
205 #ifdef __cplusplus
206 }
207 #endif
208 
209 #endif /* selectable.h */