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
proton-c
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 Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2