c++-gtk-utils: io_watch.h Source File

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 2014 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 * From version 2.0.24/2.2.7 of the library this function will not
148 * throw. (Prior to that, it could throw std::bad_alloc if memory was
149 * exhausted and the system threw in that case, or
150 * Cgu::Thread::MutexError if initialisation of the mutex in a
151 * SafeEmitterArg object failed, in which case the CallbackArg object
152 * would be disposed of.)
153 * @param fd The file descriptor.
154 * @param cb The callback object. Ownership is taken of this object,
155 * and it will be deleted when it has been finished with
156 * @param io_condition The condition to be watched for (G_IO_IN may be
157 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
158 * bitwise-ored with G_IO_ERR).
159 * @param priority The priority to be given to the watch in the main
160 * loop. In ascending order of priorities, priorities are
161 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
162 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
163 * G_PRIORITY_DEFAULT. This determines the order in which the
164 * callback will appear in the event list in the main loop, not the
165 * priority which the OS will adopt
166 * @param context The glib main context to which the watch is to be
167 * attached (the default of NULL will cause the watch to be attached
168 * to the main program loop, and this is almost always what is
169 * wanted).
170 * @return The glib source id of the watch.
171 * @note 1. Cancellation of the thread to which the watch is attached
172 * is blocked during execution of the callback.
173 * @note 2. If the callback throws an exception, the exception will be
174 * consumed to protect the main loop and a g_critical() warning will
175 * be issued.
176 * @ingroup io_watch
177 */
178 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb,
179 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
180 GMainContext* context = 0);
181
182 /**
183 * Starts an io watch in the glib main loop on a file descriptor, and
184 * executes the callback if the condition in io_condition is met.
185 * This version provides for automatic watch disconnection when the
186 * object whose function the callback represents is destroyed, via the
187 * Releaser object. It is thread-safe (it may be called in any
188 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
189 * been called. glib >= 2.32 does not require g_thread_init() to be
190 * called to be thread-safe.
191 * @param fd The file descriptor.
192 * @param cb The callback object. Ownership is taken of this object,
193 * and it will be deleted when it has been finished with.
194 * @param r A Releaser object which the protected object has as a
195 * public member.
196 * @param io_condition The condition to be watched for (G_IO_IN may be
197 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
198 * bitwise-ored with G_IO_ERR).
199 * @param priority The priority to be given to the watch in the main
200 * loop. In ascending order of priorities, priorities are
201 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
202 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
203 * G_PRIORITY_DEFAULT. This determines the order in which the
204 * callback will appear in the event list in the main loop, not the
205 * priority which the OS will adopt
206 * @param context The glib main context to which the watch is to be
207 * attached (the default of NULL will cause the watch to be attached
208 * to the main program loop, and this is almost always what is
209 * wanted).
210 * @return The glib source id of the watch.
211 * @exception std::bad_alloc This function might throw std::bad_alloc
212 * if memory is exhausted and the system throws in that case. If it
213 * does so, the CallbackArg object will be disposed of.
214 * @exception Cgu::Thread::MutexError This function might throw
215 * Cgu:Thread::MutexError if initialisation of the mutex in a
216 * SafeEmitterArg object constructed by this function fails. If it
217 * does so, the CallbackArg object will be disposed of. (It is often
218 * not worth checking for this exception, as it means either memory is
219 * exhausted or pthread has run out of other resources to create new
220 * mutexes.)
221 * @note 1. Cancellation of the thread to which the watch is attached
222 * is blocked during execution of the callback.
223 * @note 2. If the callback throws an exception, the exception will be
224 * consumed to protect the main loop and a g_critical() warning will
225 * be issued.
226 * @ingroup io_watch
227 */
228 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, Releaser& r,
229 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
230 GMainContext* context = 0);
231
232 /**
233 * Starts an io watch in the glib main loop on a file descriptor, and
234 * executes the callback if the condition in io_condition is met.
235 * This version provides the GIOCondition status which caused the
236 * callback to be invoked as the first unbound argument of the
237 * callback object. It is thread-safe (it may be called in any
238 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
239 * been called. glib >= 2.32 does not require g_thread_init() to be
240 * called to be thread-safe. From version 2.0.24/2.2.7 of the library
241 * this function will not throw. (Prior to that, it could throw
242 * std::bad_alloc if memory was exhausted and the system threw in that
243 * case, or Cgu::Thread::MutexError if initialisation of the mutex in
244 * a SafeEmitterArg object failed, in which case the CallbackArg
245 * object would be disposed of.)
246 * @param fd The file descriptor.
247 * @param cb The callback object. Ownership is taken of this object,
248 * and it will be deleted when it has been finished with.
249 * @param io_condition The condition(s) to be watched for (G_IO_IN,
250 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored).
251 * @param priority The priority to be given to the watch in the main
252 * loop. In ascending order of priorities, priorities are
253 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
254 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
255 * G_PRIORITY_DEFAULT. This determines the order in which the
256 * callback will appear in the event list in the main loop, not the
257 * priority which the OS will adopt
258 * @param context The glib main context to which the watch is to be
259 * attached (the default of NULL will cause the watch to be attached
260 * to the main program loop, and this is almost always what is
261 * wanted).
262 * @return The glib source id of the watch.
263 * @note 1. Cancellation of the thread to which the watch is attached
264 * is blocked during execution of the callback.
265 * @note 2. If the callback throws an exception, the exception will be
266 * consumed to protect the main loop and a g_critical() warning will
267 * be issued.
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 This 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 function fails. If it
312 * does so, the CallbackArg object will be disposed of. (It is often
313 * not 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 1. Cancellation of the thread to which the watch is attached
317 * is blocked during execution of the callback.
318 * @note 2. If the callback throws an exception, the exception will be
319 * consumed to protect the main loop and a g_critical() warning will
320 * be issued.
321 * @ingroup io_watch
322 *
323 * Since 2.0.0-rc2
324 */
325 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb,
326 Releaser& r, GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
327 GMainContext* context = 0);
328
329 /**
330 * Starts an io watch in the glib main loop on a file descriptor, and
331 * executes a callable object if the condition in io_condition is met.
332 * It provides the GIOCondition status which caused the callback to be
333 * invoked as the first unbound argument of the callable object, and
334 * the second is a bool& argument which if set to 'true' will cause
335 * the io watch to end. It is thread-safe (it may be called in any
336 * thread) provided that, if glib < 2.32 is used, g_thread_init() has
337 * been called. glib >= 2.32 does not require g_thread_init() to be
338 * called to be thread-safe.
339 * @param fd The file descriptor.
340 * @param func A callable object, such as formed by a lambda
341 * expression or the result of std::bind. It should take two unbound
342 * arguments of type 'GIOCondition' and 'bool&'.
343 * @param io_condition The condition to be watched for (G_IO_IN may be
344 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
345 * bitwise-ored with G_IO_ERR).
346 * @param priority The priority to be given to the watch in the main
347 * loop. In ascending order of priorities, priorities are
348 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
349 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
350 * G_PRIORITY_DEFAULT. This determines the order in which the
351 * callback will appear in the event list in the main loop, not the
352 * priority which the OS will adopt
353 * @param context The glib main context to which the watch is to be
354 * attached (the default of NULL will cause the watch to be attached
355 * to the main program loop, and this is almost always what is
356 * wanted).
357 * @return The glib source id of the watch.
358 * @exception std::bad_alloc This function might throw std::bad_alloc
359 * if memory is exhausted and the system throws in that case. (From
360 * version 2.2.7 of the library this exception will not be thrown if
361 * the library has been installed using the
362 * \--with-glib-memory-slices-no-compat configuration option. Prior
363 * to version 2.2.7 Cgu::Thread::MutexError could also be thrown if
364 * initialisation of the mutex in a SafeEmitterArg object failed.)
365 * @note 1. This function may also throw if the copy or move
366 * constructor of the callable object throws.
367 * @note 2. Cancellation of the thread to which the watch is attached
368 * is blocked during execution of the callback.
369 * @ingroup io_watch
370 *
371 * Since 2.1.0
372 */
373 // we need to use enable_if so that where this function is passed a
374 // pointer to non-const Callback::CallbackArg, or some other
375 // convertible pointer, this templated overload is dropped from the
376 // overload set, in order to support the Callback::CallbackArg pointer
377 // overloads of this function. This overload calls into the version
378 // of this function taking a pointer to const Callback::CallbackArg in
379 // order to perform type erasure.
380 template <class F,
381 class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
382 const Callback::CallbackArg<GIOCondition, bool&>*>::value
383 && !std::is_convertible<typename std::remove_reference<F>::type,
384 const Callback::CallbackArg<bool&>*>::value>::type>
385 guint start_iowatch(int fd, F&& func,
386 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
387 GMainContext* context = 0) {
388 return start_iowatch(fd, Callback::lambda<GIOCondition, bool&>(std::forward<F>(func)),
389 io_condition, priority,
390 context);
391 }
392
393 /**
394 * Starts an io watch in the glib main loop on a file descriptor, and
395 * executes a callable object if the condition in io_condition is met.
396 * It provides the GIOCondition status which caused the callback to be
397 * invoked as the first unbound argument of the callable object, and
398 * the second is a bool& argument which if set to 'true' will cause
399 * the io watch to end. This version provides for automatic watch
400 * disconnection if an object whose function the callback represents
401 * or calls into is destroyed, via the Releaser object. It is
402 * thread-safe (it may be called in any thread) provided that, if glib
403 * < 2.32 is used, g_thread_init() has been called. glib >= 2.32 does
404 * not require g_thread_init() to be called to be thread-safe.
405 * @param fd The file descriptor.
406 * @param func A callable object, such as formed by a lambda
407 * expression or the result of std::bind. It should take two unbound
408 * arguments of type 'GIOCondition' and 'bool&'.
409 * @param r A Releaser object which the protected object has as a
410 * public member.
411 * @param io_condition The condition to be watched for (G_IO_IN may be
412 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
413 * bitwise-ored with G_IO_ERR).
414 * @param priority The priority to be given to the watch in the main
415 * loop. In ascending order of priorities, priorities are
416 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
417 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
418 * G_PRIORITY_DEFAULT. This determines the order in which the
419 * callback will appear in the event list in the main loop, not the
420 * priority which the OS will adopt
421 * @param context The glib main context to which the watch is to be
422 * attached (the default of NULL will cause the watch to be attached
423 * to the main program loop, and this is almost always what is
424 * wanted).
425 * @return The glib source id of the watch.
426 * @exception std::bad_alloc This function might throw std::bad_alloc
427 * if memory is exhausted and the system throws in that case.
428 * @exception Cgu::Thread::MutexError This function might throw
429 * Cgu:Thread::MutexError if initialisation of the mutex in a
430 * SafeEmitterArg object constructed by this function fails. (It is
431 * often not worth checking for this exception, as it means either
432 * memory is exhausted or pthread has run out of other resources to
433 * create new mutexes.)
434 * @note 1. This function may also throw if the copy or move
435 * constructor of the callable object throws.
436 * @note 2. Cancellation of the thread to which the watch is attached
437 * is blocked during execution of the callback.
438 * @ingroup io_watch
439 *
440 * Since 2.1.0
441 */
442 // we need to use enable_if so that where this function is passed a
443 // pointer to non-const Callback::CallbackArg, or some other
444 // convertible pointer, this templated overload is dropped from the
445 // overload set, in order to support the Callback::CallbackArg pointer
446 // overloads of this function. This overload calls into the version
447 // of this function taking a pointer to const Callback::CallbackArg in
448 // order to perform type erasure.
449 template <class F,
450 class = typename std::enable_if<!std::is_convertible<typename std::remove_reference<F>::type,
451 const Callback::CallbackArg<GIOCondition, bool&>*>::value
452 && !std::is_convertible<typename std::remove_reference<F>::type,
453 const Callback::CallbackArg<bool&>*>::value>::type>
454 guint start_iowatch(int fd, F&& func, Releaser& r,
455 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
456 GMainContext* context = 0) {
457 return start_iowatch(fd, Callback::lambda<GIOCondition, bool&>(std::forward<F>(func)), r,
458 io_condition, priority,
459 context);
460 }
461
462 } // namespace Cgu
463
464 #endif