c++-gtk-utils

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

io_watch.h
Go to the documentation of this file.
1 /* Copyright (C) 2005 to 2013 Chris Vine
2
3 The library comprised in this file or of which this file is part is
4 distributed by Chris Vine under the GNU Lesser General Public
5 License as follows:
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public License
9 as published by the Free Software Foundation; either version 2.1 of
10 the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License, version 2.1, for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License, version 2.1, along with this library (see the file LGPL.TXT
19 which came with this source code package in the c++-gtk-utils
20 sub-directory); if not, write to the Free Software Foundation, Inc.,
21 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
22
23 */
24
25 #ifndef CGU_IO_WATCH_H
26 #define CGU_IO_WATCH_H
27
28 /**
29 */
30
31 /**
32 * @defgroup io_watch io_watch
33 *
34 * \#include <c++-gtk-utils/io_watch.h>
35 *
36 * The start_iowatch() function connects a Unix file descriptor to an
37 * event loop owned by a GMainContext object (normally the main
38 * program loop). It both saves the overhead of having to construct a
39 * GIOChannel object where the only thing wanted is to execute a
40 * callback when there is something to be read from a pipe, fifo or
41 * socket or a pipe or fifo can be written to, and it also provides
42 * for automatic disconnection when an object whose function the
43 * callback represents or calls into is destroyed.
44 *
45 * For the GIOCondition argument of start_iowatch(), G_IO_IN can be
46 * bitwise-ORed with G_IO_HUP, and should be if the callback has the
47 * task of cleaning up if EOF is reached (see
48 * http://www.greenend.org.uk/rjk/2001/06/poll.html ), which is
49 * detected by read() returning 0. A cast will be required to do this
50 * for the third argument of start_iowatch() (that is, pass
51 * GIOCondition(G_IO_IN | G_IO_HUP)). In addition, G_IO_IN and
52 * G_IO_OUT can be bitwise-ORed with G_IO_ERR (and passed as
53 * GIOCondition(G_IO_IN | G_IO_HUP | G_IO_ERR) or
54 * GIOCondition(G_IO_OUT | G_IO_ERR)), which would be detected in the
55 * callback by read() or write() returning -1.
56 *
57 * The start_iowatch() function has a number of overloads for the
58 * callback to be executed when the file descriptor becomes available
59 * for reading or writing. The simplest to use take an ordinary
60 * callable object, such as a lambda expression or the return value of
61 * std::bind. For these, the callable object should take two unbound
62 * arguments, the first a GIOCondition type and the second a bool&
63 * type. When the callable object is executed, the GIOCondition
64 * argument is passed a value representing the bitwise-ORed events
65 * which caused the call: this enables a single watch to be provided
66 * for both reading and writing (if the file descriptor has been
67 * opened for reading and writing), by testing for G_IO_IN and
68 * G_IO_OUT on that argument in the callback function. It also
69 * enables, by testing for G_IO_HUP and G_IO_ERR, a hang-up or error
70 * condition to be detected without having to inspect the return value
71 * of read() or write() (but note the test results referred to in
72 * http://www.greenend.org.uk/rjk/2001/06/poll.html , which show that
73 * the ending of a connection can only reliably be determined by
74 * testing whether read() returns 0, or whether the iostream wrapper
75 * on top of it reports end of file after attempting a read.)
76 *
77 * The second bool& argument can be used to end the watch. If it is
78 * set by the callable object when executed to false, say because
79 * end-of-file has been reached, then the watch will be ended and all
80 * resources connected with it deleted without further user action
81 * being required (there is no need for the callable object to set it
82 * to true if the watch is to continue, as that is the default).
83 *
84 * Other overloads of start_iowatch() take the more explicitly typed
85 * Callback::CallbackArg<GIOCondition, bool&> callback object (as
86 * constructed with Callback::lambda(), Callback::make() or
87 * Callback::make_ref()) instead of a simple callable object, and
88 * others take a Callback::CallbackArg<bool&> object for cases where a
89 * GIOCondition argument is unnecessary (although there is nothing
90 * stopping the other overloads being used and that argument being
91 * ignored, and that version is mainly kept to retain compatibility
92 * with the 1.2 and 2.0 series of the library).
93 *
94 * All of the start_iowatch() overloads have an option to take a
95 * Callback::Releaser object as their third argument, which provides
96 * for automatic ceasing of the watch if the target object which has
97 * the Releaser as a member is destroyed. (Note that for this to be
98 * race free, the lifetime of the remote target object whose method is
99 * to be invoked must be determined by the thread to whose main loop
100 * the watch has been attached. When the main loop begins invoking
101 * the execution of the watch callback, the remote object must either
102 * wholly exist, in which case the callback will be invoked, or have
103 * been destroyed, in which case the callback will be ignored, and not
104 * be in some transient half-state governed by another thread.)
105 *
106 * start_iowatch() is thread-safe (it may be called in any thread)
107 * provided that, if glib < 2.32 is used, the glib main loop has been
108 * made thread-safe by a call to g_thread_init(). glib >= 2.32 does
109 * not require g_thread_init() to be called in order to be
110 * thread-safe.
111 *
112 * As mentioned above, the connected callback passed to
113 * start_iowatch() has an unbound bool& argument. The watch will be
114 * ended if that argument is set by the connected callback to false,
115 * say because end-of-file has been reached. In addition, the watch
116 * will be ended automatically and resources deleted if (i) as
117 * mentioned above, the callback passed to start_iowatch() is
118 * protected by a Releaser object and the target object having the
119 * Releaser as a member is destroyed, or (ii) g_source_remove() is
120 * called on the source id returned by start_iowatch() (where the
121 * watch is attached to the default main context) or
122 * g_source_destroy() is called on the GSource object obtained from
123 * that id with g_main_context_find_source_by_id() (where the watch
124 * has been attached to a non-default main context). If the source
125 * has been removed automatically by virtue of the bool& argument
126 * being set to false or by virtue of a Releaser object releasing,
127 * g_source_remove() or g_source_destroy() should not afterwards be
128 * called in respect of the id value returned by start_iowatch() in
129 * case it has been reused by the main context concerned in the
130 * meantime.
131 */
132
133 #include <glib.h>
134 #include <c++-gtk-utils/callback.h>
135 #include <c++-gtk-utils/cgu_config.h>
136
137 namespace Cgu {
138
139 class Releaser;
140
141 /**
142 * Starts an io watch in the glib main loop on a file descriptor, and
143 * executes the callback if the condition in io_condition is met. It
144 * is thread-safe (it may be called in any thread) provided that, if
145 * glib < 2.32 is used, g_thread_init() has been called. glib >= 2.32
146 * does not require g_thread_init() to be called to be thread-safe.
147 * @param fd The file descriptor.
148 * @param cb The callback object. Ownership is taken of this object,
149 * and it will be deleted when it has been finished with
150 * @param io_condition The condition to be watched for (G_IO_IN may be
151 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
152 * bitwise-ored with G_IO_ERR).
153 * @param priority The priority to be given to the watch in the main
154 * loop. In ascending order of priorities, priorities are
155 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
156 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
157 * G_PRIORITY_DEFAULT. This determines the order in which the
158 * callback will appear in the event list in the main loop, not the
159 * priority which the OS will adopt
160 * @param context The glib main context to which the watch is to be
161 * attached (the default of NULL will cause the watch to be attached
162 * to the main program loop, and this is almost always what is
163 * wanted).
164 * @return The glib source id of the watch.
165 * @exception std::bad_alloc The function might throw std::bad_alloc
166 * if memory is exhausted and the system throws in that case. If it
167 * does so, the CallbackArg object will be disposed of.
168 * @exception Cgu::Thread::MutexError This function might throw
169 * Cgu:Thread::MutexError if initialisation of the mutex in a
170 * SafeEmitterArg object constructed by this method fails. If it does
171 * so, the CallbackArg object will be disposed of. (It is often not
172 * worth checking for this exception, as it means either memory is
173 * exhausted or pthread has run out of other resources to create new
174 * mutexes.)
175 * @note Cancellation of the thread to which the watch is attached is
176 * blocked during execution of the callback.
177 * @ingroup io_watch
178 */
179 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb,
180 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
181 GMainContext* context = 0);
182
183 /**
184 * Starts an io watch in the glib main loop on a file descriptor, and
185 * executes the callback if the condition in io_condition is met.
186 * This version provides for automatic watch disconnection when the
187 * object whose function the callback represents is destroyed, via the
188 * Releaser object. It is thread-safe (it may be called in any
189 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
190 * been called. glib >= 2.32 does not require g_thread_init() to be
191 * called to be thread-safe.
192 * @param fd The file descriptor.
193 * @param cb The callback object. Ownership is taken of this object,
194 * and it will be deleted when it has been finished with.
195 * @param r A Releaser object which the protected object has as a
196 * public member.
197 * @param io_condition The condition to be watched for (G_IO_IN may be
198 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
199 * bitwise-ored with G_IO_ERR).
200 * @param priority The priority to be given to the watch in the main
201 * loop. In ascending order of priorities, priorities are
202 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
203 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
204 * G_PRIORITY_DEFAULT. This determines the order in which the
205 * callback will appear in the event list in the main loop, not the
206 * priority which the OS will adopt
207 * @param context The glib main context to which the watch is to be
208 * attached (the default of NULL will cause the watch to be attached
209 * to the main program loop, and this is almost always what is
210 * wanted).
211 * @return The glib source id of the watch.
212 * @exception std::bad_alloc The function might throw std::bad_alloc
213 * if memory is exhausted and the system throws in that case. If it
214 * does so, the CallbackArg object will be disposed of.
215 * @exception Cgu::Thread::MutexError This function might throw
216 * Cgu:Thread::MutexError if initialisation of the mutex in a
217 * SafeEmitterArg object constructed by this method fails. If it does
218 * so, the CallbackArg object will be disposed of. (It is often not
219 * worth checking for this exception, as it means either memory is
220 * exhausted or pthread has run out of other resources to create new
221 * mutexes.)
222 * @note Cancellation of the thread to which the watch is attached is
223 * blocked during execution of the callback.
224 * @ingroup io_watch
225 */
226 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, Releaser& r,
227 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
228 GMainContext* context = 0);
229
230 /**
231 * Starts an io watch in the glib main loop on a file descriptor, and
232 * executes the callback if the condition in io_condition is met.
233 * This version provides the GIOCondition status which caused the
234 * callback to be invoked as the first unbound argument of the
235 * callback object. It is thread-safe (it may be called in any
236 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
237 * been called. glib >= 2.32 does not require g_thread_init() to be
238 * called to be thread-safe.
239 * @param fd The file descriptor.
240 * @param cb The callback object. Ownership is taken of this object,
241 * and it will be deleted when it has been finished with.
242 * @param io_condition The condition(s) to be watched for (G_IO_IN,
243 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored).
244 * @param priority The priority to be given to the watch in the main
245 * loop. In ascending order of priorities, priorities are
246 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
247 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
248 * G_PRIORITY_DEFAULT. This determines the order in which the
249 * callback will appear in the event list in the main loop, not the
250 * priority which the OS will adopt
251 * @param context The glib main context to which the watch is to be
252 * attached (the default of NULL will cause the watch to be attached
253 * to the main program loop, and this is almost always what is
254 * wanted).
255 * @return The glib source id of the watch.
256 * @exception std::bad_alloc The function might throw std::bad_alloc
257 * if memory is exhausted and the system throws in that case. If it
258 * does so, the CallbackArg object will be disposed of.
259 * @exception Cgu::Thread::MutexError This function might throw
260 * Cgu:Thread::MutexError if initialisation of the mutex in a
261 * SafeEmitterArg object constructed by this method fails. If it does
262 * so, the CallbackArg object will be disposed of. (It is often not
263 * worth checking for this exception, as it means either memory is
264 * exhausted or pthread has run out of other resources to create new
265 * mutexes.)
266 * @note Cancellation of the thread to which the watch is attached is
267 * blocked during execution of the callback.
268 * @ingroup io_watch
269 *
270 * Since 2.0.0-rc2
271 */
272 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb,
273 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
274 GMainContext* context = 0);
275
276 /**
277 * Starts an io watch in the glib main loop on a file descriptor, and
278 * executes the callback if the condition in io_condition is met.
279 * This version provides both automatic watch disconnection when the
280 * object whose function the callback represents is destroyed, via the
281 * Releaser object, and provides the GIOCondition status which caused
282 * the callback to be invoked as the first unbound argument of the
283 * callback object. It is thread-safe (it may be called in any
284 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
285 * been called. glib >= 2.32 does not require g_thread_init() to be
286 * called to be thread-safe.
287 * @param fd The file descriptor.
288 * @param cb The callback object. Ownership is taken of this object,
289 * and it will be deleted when it has been finished with.
290 * @param r A Releaser object which the protected object has as a
291 * public member.
292 * @param io_condition The condition(s) to be watched for (G_IO_IN,
293 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored).
294 * @param priority The priority to be given to the watch in the main
295 * loop. In ascending order of priorities, priorities are
296 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
297 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
298 * G_PRIORITY_DEFAULT. This determines the order in which the
299 * callback will appear in the event list in the main loop, not the
300 * priority which the OS will adopt
301 * @param context The glib main context to which the watch is to be
302 * attached (the default of NULL will cause the watch to be attached
303 * to the main program loop, and this is almost always what is
304 * wanted).
305 * @return The glib source id of the watch.
306 * @exception std::bad_alloc The function might throw std::bad_alloc
307 * if memory is exhausted and the system throws in that case. If it
308 * does so, the CallbackArg object will be disposed of.
309 * @exception Cgu::Thread::MutexError This function might throw
310 * Cgu:Thread::MutexError if initialisation of the mutex in a
311 * SafeEmitterArg object constructed by this method fails. If it does
312 * so, the CallbackArg object will be disposed of. (It is often not
313 * worth checking for this exception, as it means either memory is
314 * exhausted or pthread has run out of other resources to create new
315 * mutexes.)
316 * @note Cancellation of the thread to which the watch is attached is
317 * blocked during execution of the callback.
318 * @ingroup io_watch
319 *
320 * Since 2.0.0-rc2
321 */
322 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb,
323 Releaser& r, GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
324 GMainContext* context = 0);
325
326 /**
327 * Starts an io watch in the glib main loop on a file descriptor, and
328 * executes a callable object if the condition in io_condition is met.
329 * It provides the GIOCondition status which caused the callback to be
330 * invoked as the first unbound argument of the callable object, and
331 * the second is a bool& argument which if set to 'true' will cause
332 * the io watch to end. It is thread-safe (it may be called in any
333 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
334 * been called. glib >= 2.32 does not require g_thread_init() to be
335 * called to be thread-safe.
336 * @param fd The file descriptor.
337 * @param func A callable object, such as formed by a lambda
338 * expression or the result of std::bind. It should take two unbound
339 * arguments of type 'GIOCondition' and 'bool&'.
340 * @param io_condition The condition to be watched for (G_IO_IN may be
341 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
342 * bitwise-ored with G_IO_ERR).
343 * @param priority The priority to be given to the watch in the main
344 * loop. In ascending order of priorities, priorities are
345 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
346 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
347 * G_PRIORITY_DEFAULT. This determines the order in which the
348 * callback will appear in the event list in the main loop, not the
349 * priority which the OS will adopt
350 * @param context The glib main context to which the watch is to be
351 * attached (the default of NULL will cause the watch to be attached
352 * to the main program loop, and this is almost always what is
353 * wanted).
354 * @return The glib source id of the watch.
355 * @exception std::bad_alloc The function might throw std::bad_alloc
356 * if memory is exhausted and the system throws in that case.
357 * @exception Cgu::Thread::MutexError This function might throw
358 * Cgu:Thread::MutexError if initialisation of the mutex in a
359 * SafeEmitterArg object constructed by this method fails. (It is
360 * often not worth checking for this exception, as it means either
361 * memory is exhausted or pthread has run out of other resources to
362 * create new mutexes.)
363 * @note 1. This function may also throw if the copy or move
364 * constructor of the callable object throws.
365 * @note 2. Cancellation of the thread to which the watch is attached
366 * is blocked during execution of the callback.
367 * @ingroup io_watch
368 *
369 * Since 2.1.0
370 */
371 // we need to use enable_if so that where this function is passed a
372 // pointer to non-const Callback::CallbackArg, or some other
373 // convertible pointer, this templated overload is dropped from the
374 // overload set, in order to support the Callback::CallbackArg pointer
375 // overloads of this function. This overload calls into the version
376 // of this function taking a pointer to const Callback::CallbackArg in
377 // order to perform type erasure.
378 template <class F,
379 class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
380 const Callback::CallbackArg<GIOCondition, bool&>*>::value
381 && !std::is_convertible<typename std::remove_reference<F>::type,
382 const Callback::CallbackArg<bool&>*>::value>::type>
383 guint start_iowatch(int fd, F&& func,
384 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
385 GMainContext* context = 0) {
386 return start_iowatch(fd, Callback::lambda<GIOCondition, bool&>(std::forward<F>(func)),
387 io_condition, priority,
388 context);
389 }
390
391 /**
392 * Starts an io watch in the glib main loop on a file descriptor, and
393 * executes a callable object if the condition in io_condition is met.
394 * It provides the GIOCondition status which caused the callback to be
395 * invoked as the first unbound argument of the callable object, and
396 * the second is a bool& argument which if set to 'true' will cause
397 * the io watch to end. This version provides for automatic watch
398 * disconnection if an object whose function the callback represents
399 * or calls into is destroyed, via the Releaser object. It is
400 * thread-safe (it may be called in any thread) provided that, if glib
401 * < 2.32 is used, g_thread_init() has been called. glib >= 2.32 does
402 * not require g_thread_init() to be called to be thread-safe.
403 * @param fd The file descriptor.
404 * @param func A callable object, such as formed by a lambda
405 * expression or the result of std::bind. It should take two unbound
406 * arguments of type 'GIOCondition' and 'bool&'.
407 * @param r A Releaser object which the protected object has as a
408 * public member.
409 * @param io_condition The condition to be watched for (G_IO_IN may be
410 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
411 * bitwise-ored with G_IO_ERR).
412 * @param priority The priority to be given to the watch in the main
413 * loop. In ascending order of priorities, priorities are
414 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
415 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
416 * G_PRIORITY_DEFAULT. This determines the order in which the
417 * callback will appear in the event list in the main loop, not the
418 * priority which the OS will adopt
419 * @param context The glib main context to which the watch is to be
420 * attached (the default of NULL will cause the watch to be attached
421 * to the main program loop, and this is almost always what is
422 * wanted).
423 * @return The glib source id of the watch.
424 * @exception std::bad_alloc The function might throw std::bad_alloc
425 * if memory is exhausted and the system throws in that case.
426 * @exception Cgu::Thread::MutexError This function might throw
427 * Cgu:Thread::MutexError if initialisation of the mutex in a
428 * SafeEmitterArg object constructed by this method fails. (It is
429 * often not worth checking for this exception, as it means either
430 * memory is exhausted or pthread has run out of other resources to
431 * create new mutexes.)
432 * @note 1. This function may also throw if the copy or move
433 * constructor of the callable object throws.
434 * @note 2. Cancellation of the thread to which the watch is attached
435 * is blocked during execution of the callback.
436 * @ingroup io_watch
437 *
438 * Since 2.1.0
439 */
440 // we need to use enable_if so that where this function is passed a
441 // pointer to non-const Callback::CallbackArg, or some other
442 // convertible pointer, this templated overload is dropped from the
443 // overload set, in order to support the Callback::CallbackArg pointer
444 // overloads of this function. This overload calls into the version
445 // of this function taking a pointer to const Callback::CallbackArg in
446 // order to perform type erasure.
447 template <class F,
448 class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
449 const Callback::CallbackArg<GIOCondition, bool&>*>::value
450 && !std::is_convertible<typename std::remove_reference<F>::type,
451 const Callback::CallbackArg<bool&>*>::value>::type>
452 guint start_iowatch(int fd, F&& func, Releaser& r,
453 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
454 GMainContext* context = 0) {
455 return start_iowatch(fd, Callback::lambda<GIOCondition, bool&>(std::forward<F>(func)), r,
456 io_condition, priority,
457 context);
458 }
459
460 } // namespace Cgu
461
462 #endif