proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
proton
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
*/
47
typedef
pn_iterator_t
pn_selectables_t
;
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
*/
69
typedef
struct
pn_selectable_t
pn_selectable_t
;
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
*/
99
PN_EXTERN
pn_socket_t
pn_selectable_fd
(
pn_selectable_t
*selectable);
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
*/
111
PN_EXTERN
ssize_t
pn_selectable_capacity
(
pn_selectable_t
*selectable);
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
*/
135
PN_EXTERN
pn_timestamp_t
pn_selectable_deadline
(
pn_selectable_t
*selectable);
136
137
/**
138
* Notify a selectable that the file descriptor is readable.
139
*
140
* @param[in] selectable a selectable object
141
*/
142
PN_EXTERN
void
pn_selectable_readable
(
pn_selectable_t
*selectable);
143
144
/**
145
* Notify a selectable that the file descriptor is writable.
146
*
147
* @param[in] selectable a selectable object
148
*/
149
PN_EXTERN
void
pn_selectable_writable
(
pn_selectable_t
*selectable);
150
151
/**
152
* Notify a selectable that its deadline has expired.
153
*
154
* @param[in] selectable a selectable object
155
*/
156
PN_EXTERN
void
pn_selectable_expired
(
pn_selectable_t
*selectable);
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
*/
168
PN_EXTERN
bool
pn_selectable_is_registered
(
pn_selectable_t
*selectable);
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
*/
192
PN_EXTERN
bool
pn_selectable_is_terminal
(
pn_selectable_t
*selectable);
193
194
/**
195
* Free a selectable object.
196
*
197
* @param[in] selectable a selectable object (or NULL)
198
*/
199
PN_EXTERN
void
pn_selectable_free
(
pn_selectable_t
*selectable);
200
201
/**
202
* @}
203
*/
204
205
#ifdef __cplusplus
206
}
207
#endif
208
209
#endif
/* selectable.h */
Generated on Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1