c++-gtk-utils
io_watch.h
Go to the documentation of this file.
1 /* Copyright (C) 2005 to 2012 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 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  * Two of the four overloaded start_iowatch() functions also take a
58  * Callback object having a GIOCondition type and bool& type as their
59  * unbound arguments (the other two overloads only have callbacks
60  * taking a single bool& unbound argument). The overloads taking a
61  * Callback object with an unbound GIOCondition argument type are,
62  * when the callback function is executed, passed a GIOCondition value
63  * to that argument, representing the bitwise-ORed events which caused
64  * the call: this enables a single watch to be provided for both
65  * reading and writing (if the file descriptor has been opened for
66  * reading and writing), by testing for G_IO_IN and G_IO_OUT on that
67  * argument in the callback function. It also enables, by testing for
68  * G_IO_HUP and G_IO_ERR, a hang-up or error condition to be detected
69  * without having to inspect the return value of read() or write()
70  * (but note the test results referred to in
71  * http://www.greenend.org.uk/rjk/2001/06/poll.html , which show that
72  * the ending of a connection can only reliably be determined by
73  * testing whether read() returns 0, or whether the iostream wrapper
74  * on top of it reports end of file after attempting a read.)
75  *
76  * start_iowatch() is thread-safe (it may be called in any thread)
77  * provided that, if glib < 2.32 is used, the glib main loop has been
78  * made thread-safe by a call to g_thread_init(). glib >= 2.32 does
79  * not require g_thread_init() to be called in order to be
80  * thread-safe.
81  *
82  * start_iowatch() takes ownership of the passed Callback object. Two
83  * of the four start_iowatch() overloads take a Callback::Releaser
84  * object as their third argument, which provides for automatic
85  * ceasing of the watch if the target object which has the Releaser as
86  * a member is destroyed. (Note that for this to be race free, the
87  * lifetime of the remote target object whose method is to be invoked
88  * must be determined by the thread to whose main loop the watch has
89  * been attached. When the main loop begins invoking the execution of
90  * the watch callback, the remote object must either wholly exist, in
91  * which case the callback will be invoked, or have been destroyed, in
92  * which case the callback will be ignored, and not be in some
93  * transient half-state governed by another thread.)
94  *
95  * As mentioned above, the connected function encapsulated by the
96  * callback passed to start_iowatch() must have a second (or only)
97  * unbound bool& argument. If that bool& argument is set by the
98  * connected function to false, say because end-of-file has been
99  * reached, then the watch will be ended and all resources connected
100  * with it deleted without further user action being required (there
101  * is no need for the connected function to set it to true if the
102  * watch is to continue, as that is the default). In addition, the
103  * watch will be ended automatically and resources deleted if (i) as
104  * mentioned above, the callback passed to start_iowatch() is
105  * protected by a Releaser object and the target object whose method
106  * is encapsulated by the callback is destroyed, or (ii)
107  * g_source_remove() is called on the source id returned by
108  * start_iowatch() (where the watch is attached to the default main
109  * context) or g_source_destroy() is called on the GSource object
110  * obtained from that id with g_main_context_find_source_by_id()
111  * (where the watch has been attached to a non-default main context).
112  * If the source has been removed automatically by virtue of the bool&
113  * argument being set to false or by virtue of a Releaser object
114  * releasing, g_source_remove() or g_source_destroy() should not
115  * afterwards be called in respect of the id value returned by
116  * start_iowatch() in case it has been reused by the main context
117  * concerned in the meantime.
118  */
119 
120 #include <glib.h>
121 #include <c++-gtk-utils/callback.h>
123 
124 namespace Cgu {
125 
126 class Releaser;
127 
128 /**
129  * Starts an io watch in the glib main loop on a file descriptor, and
130  * executes the callback if the condition in io_condition is met. It
131  * is thread-safe (it may be called in any thread) provided that, if
132  * glib < 2.32 is used, g_thread_init() has been called. glib >= 2.32
133  * does not require g_thread_init() to be called to be thread-safe.
134  * @param fd The file descriptor.
135  * @param cb The callback object. Ownership is taken of this object,
136  * and it will be deleted when it has been finished with
137  * @param io_condition The condition to be watched for (G_IO_IN may be
138  * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
139  * bitwise-ored with G_IO_ERR).
140  * @param priority The priority to be given to the watch in the main
141  * loop. In ascending order of priorities, priorities are
142  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
143  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
144  * G_PRIORITY_DEFAULT. This determines the order in which the
145  * callback will appear in the event list in the main loop, not the
146  * priority which the OS will adopt
147  * @param context The glib main context to which the watch is to be
148  * attached (the default of NULL will cause the watch to be attached
149  * to the main program loop, and this is almost always what is
150  * wanted).
151  * @return The glib source id of the watch.
152  * @exception std::bad_alloc The method might throw std::bad_alloc if
153  * memory is exhausted and the system throws in that case. If it does
154  * so, the CallbackArg object will be disposed of.
155  * @exception Cgu::Thread::MutexError This method might throw
156  * Cgu:Thread::MutexError if initialisation of the mutex in a
157  * SafeEmitterArg object constructed by this method fails. If it does
158  * so, the CallbackArg object will be disposed of. (It is often not
159  * worth checking for this exception, as it means either memory is
160  * exhausted or pthread has run out of other resources to create new
161  * mutexes.)
162  * @note Cancellation of the thread to which the watch is attached is
163  * blocked during execution of the callback.
164  * @ingroup io_watch
165  */
166 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb,
167  GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
168  GMainContext* context = 0);
169 
170 /**
171  * Starts an io watch in the glib main loop on a file descriptor, and
172  * executes the callback if the condition in io_condition is met.
173  * This version provides for automatic watch disconnection when the
174  * object whose function the callback represents is destroyed, via the
175  * Releaser object. It is thread-safe (it may be called in any
176  * thread) provided that, if glib < 2.32 is used, g_thread_init() has
177  * been called. glib >= 2.32 does not require g_thread_init() to be
178  * called to be thread-safe.
179  * @param fd The file descriptor.
180  * @param cb The callback object. Ownership is taken of this object,
181  * and it will be deleted when it has been finished with.
182  * @param r A Releaser object which the protected object has as a
183  * public member.
184  * @param io_condition The condition to be watched for (G_IO_IN may be
185  * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be
186  * bitwise-ored with G_IO_ERR).
187  * @param priority The priority to be given to the watch in the main
188  * loop. In ascending order of priorities, priorities are
189  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
190  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
191  * G_PRIORITY_DEFAULT. This determines the order in which the
192  * callback will appear in the event list in the main loop, not the
193  * priority which the OS will adopt
194  * @param context The glib main context to which the watch is to be
195  * attached (the default of NULL will cause the watch to be attached
196  * to the main program loop, and this is almost always what is
197  * wanted).
198  * @return The glib source id of the watch.
199  * @exception std::bad_alloc The method might throw std::bad_alloc if
200  * memory is exhausted and the system throws in that case. If it does
201  * so, the CallbackArg object will be disposed of.
202  * @exception Cgu::Thread::MutexError This method might throw
203  * Cgu:Thread::MutexError if initialisation of the mutex in a
204  * SafeEmitterArg object constructed by this method fails. If it does
205  * so, the CallbackArg object will be disposed of. (It is often not
206  * worth checking for this exception, as it means either memory is
207  * exhausted or pthread has run out of other resources to create new
208  * mutexes.)
209  * @note Cancellation of the thread to which the watch is attached is
210  * blocked during execution of the callback.
211  * @ingroup io_watch
212  */
213 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, Releaser& r,
214  GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
215  GMainContext* context = 0);
216 
217 /**
218  * Starts an io watch in the glib main loop on a file descriptor, and
219  * executes the callback if the condition in io_condition is met.
220  * This version provides the GIOCondition status which caused the
221  * callback to be invoked as the first unbound argument of the
222  * callback object. It is thread-safe (it may be called in any
223  * thread) provided that, if glib < 2.32 is used, g_thread_init() has
224  * been called. glib >= 2.32 does not require g_thread_init() to be
225  * called to be thread-safe.
226  * @param fd The file descriptor.
227  * @param cb The callback object. Ownership is taken of this object,
228  * and it will be deleted when it has been finished with.
229  * @param io_condition The condition(s) to be watched for (G_IO_IN,
230  * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored).
231  * @param priority The priority to be given to the watch in the main
232  * loop. In ascending order of priorities, priorities are
233  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
234  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
235  * G_PRIORITY_DEFAULT. This determines the order in which the
236  * callback will appear in the event list in the main loop, not the
237  * priority which the OS will adopt
238  * @param context The glib main context to which the watch is to be
239  * attached (the default of NULL will cause the watch to be attached
240  * to the main program loop, and this is almost always what is
241  * wanted).
242  * @return The glib source id of the watch.
243  * @exception std::bad_alloc The method might throw std::bad_alloc if
244  * memory is exhausted and the system throws in that case. If it does
245  * so, the CallbackArg object will be disposed of.
246  * @exception Cgu::Thread::MutexError This method might throw
247  * Cgu:Thread::MutexError if initialisation of the mutex in a
248  * SafeEmitterArg object constructed by this method fails. If it does
249  * so, the CallbackArg object will be disposed of. (It is often not
250  * worth checking for this exception, as it means either memory is
251  * exhausted or pthread has run out of other resources to create new
252  * mutexes.)
253  * @note Cancellation of the thread to which the watch is attached is
254  * blocked during execution of the callback.
255  * @ingroup io_watch
256  *
257  * Since 2.0.0-rc2
258  */
259 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb,
260  GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
261  GMainContext* context = 0);
262 
263 /**
264  * Starts an io watch in the glib main loop on a file descriptor, and
265  * executes the callback if the condition in io_condition is met.
266  * This version provides both automatic watch disconnection when the
267  * object whose function the callback represents is destroyed, via the
268  * Releaser object, and provides the GIOCondition status which caused
269  * the callback to be invoked as the first unbound argument of the
270  * callback object. It is thread-safe (it may be called in any
271  * thread) provided that, if glib < 2.32 is used, g_thread_init() has
272  * been called. glib >= 2.32 does not require g_thread_init() to be
273  * called to be thread-safe.
274  * @param fd The file descriptor.
275  * @param cb The callback object. Ownership is taken of this object,
276  * and it will be deleted when it has been finished with.
277  * @param r A Releaser object which the protected object has as a
278  * public member.
279  * @param io_condition The condition(s) to be watched for (G_IO_IN,
280  * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored).
281  * @param priority The priority to be given to the watch in the main
282  * loop. In ascending order of priorities, priorities are
283  * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE,
284  * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is
285  * G_PRIORITY_DEFAULT. This determines the order in which the
286  * callback will appear in the event list in the main loop, not the
287  * priority which the OS will adopt
288  * @param context The glib main context to which the watch is to be
289  * attached (the default of NULL will cause the watch to be attached
290  * to the main program loop, and this is almost always what is
291  * wanted).
292  * @return The glib source id of the watch.
293  * @exception std::bad_alloc The method might throw std::bad_alloc if
294  * memory is exhausted and the system throws in that case. If it does
295  * so, the CallbackArg object will be disposed of.
296  * @exception Cgu::Thread::MutexError This method might throw
297  * Cgu:Thread::MutexError if initialisation of the mutex in a
298  * SafeEmitterArg object constructed by this method fails. If it does
299  * so, the CallbackArg object will be disposed of. (It is often not
300  * worth checking for this exception, as it means either memory is
301  * exhausted or pthread has run out of other resources to create new
302  * mutexes.)
303  * @note Cancellation of the thread to which the watch is attached is
304  * blocked during execution of the callback.
305  * @ingroup io_watch
306  *
307  * Since 2.0.0-rc2
308  */
309 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb,
310  Releaser& r, GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT,
311  GMainContext* context = 0);
312 
313 } // namespace Cgu
314 
315 #endif