c++-gtk-utils
|
00001 /* Copyright (C) 2005 to 2012 Chris Vine 00002 00003 The library comprised in this file or of which this file is part is 00004 distributed by Chris Vine under the GNU Lesser General Public 00005 License as follows: 00006 00007 This library is free software; you can redistribute it and/or 00008 modify it under the terms of the GNU Lesser General Public License 00009 as published by the Free Software Foundation; either version 2.1 of 00010 the License, or (at your option) any later version. 00011 00012 This library is distributed in the hope that it will be useful, but 00013 WITHOUT ANY WARRANTY; without even the implied warranty of 00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00015 Lesser General Public License, version 2.1, for more details. 00016 00017 You should have received a copy of the GNU Lesser General Public 00018 License, version 2.1, along with this library (see the file LGPL.TXT 00019 which came with this source code package in the c++-gtk-utils 00020 sub-directory); if not, write to the Free Software Foundation, Inc., 00021 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 00022 00023 */ 00024 00025 #ifndef CGU_IO_WATCH_H 00026 #define CGU_IO_WATCH_H 00027 00028 /** 00029 */ 00030 00031 /** 00032 * @defgroup io_watch io_watch 00033 * 00034 * \#include <c++-gtk-utils/io_watch.h> 00035 * 00036 * The start_iowatch() function connects a Unix file descriptor to an 00037 * event loop owned by a GMainContext object (normally the main 00038 * program loop). It both saves the overhead of having to construct a 00039 * GIOChannel object where the only thing wanted is to execute a 00040 * callback when there is something to be read from a pipe, fifo or 00041 * socket or a pipe or fifo can be written to, and it also provides 00042 * for automatic disconnection when an object whose function the 00043 * callback represents is destroyed. 00044 * 00045 * For the GIOCondition argument of start_iowatch(), G_IO_IN can be 00046 * bitwise-ORed with G_IO_HUP, and should be if the callback has the 00047 * task of cleaning up if EOF is reached (see 00048 * http://www.greenend.org.uk/rjk/2001/06/poll.html ), which is 00049 * detected by read() returning 0. A cast will be required to do this 00050 * for the third argument of start_iowatch() (that is, pass 00051 * GIOCondition(G_IO_IN | G_IO_HUP)). In addition, G_IO_IN and 00052 * G_IO_OUT can be bitwise-ORed with G_IO_ERR (and passed as 00053 * GIOCondition(G_IO_IN | G_IO_HUP | G_IO_ERR) or 00054 * GIOCondition(G_IO_OUT | G_IO_ERR)), which would be detected in the 00055 * callback by read() or write() returning -1. 00056 * 00057 * Two of the four overloaded start_iowatch() functions also take a 00058 * Callback object having a GIOCondition type and bool& type as their 00059 * unbound arguments (the other two overloads only have callbacks 00060 * taking a single bool& unbound argument). The overloads taking a 00061 * Callback object with an unbound GIOCondition argument type are, 00062 * when the callback function is executed, passed a GIOCondition value 00063 * to that argument, representing the bitwise-ORed events which caused 00064 * the call: this enables a single watch to be provided for both 00065 * reading and writing (if the file descriptor has been opened for 00066 * reading and writing), by testing for G_IO_IN and G_IO_OUT on that 00067 * argument in the callback function. It also enables, by testing for 00068 * G_IO_HUP and G_IO_ERR, a hang-up or error condition to be detected 00069 * without having to inspect the return value of read() or write() 00070 * (but note the test results referred to in 00071 * http://www.greenend.org.uk/rjk/2001/06/poll.html , which show that 00072 * the ending of a connection can only reliably be determined by 00073 * testing whether read() returns 0, or whether the iostream wrapper 00074 * on top of it reports end of file after attempting a read.) 00075 * 00076 * start_iowatch() is thread-safe (it may be called in any thread) 00077 * provided that, if glib < 2.32 is used, the glib main loop has been 00078 * made thread-safe by a call to g_thread_init(). glib >= 2.32 does 00079 * not require g_thread_init() to be called in order to be 00080 * thread-safe. 00081 * 00082 * start_iowatch() takes ownership of the passed Callback object. Two 00083 * of the four start_iowatch() overloads take a Callback::Releaser 00084 * object as their third argument, which provides for automatic 00085 * ceasing of the watch if the target object which has the Releaser as 00086 * a member is destroyed. (Note that for this to be race free, the 00087 * lifetime of the remote target object whose method is to be invoked 00088 * must be determined by the thread to whose main loop the watch has 00089 * been attached. When the main loop begins invoking the execution of 00090 * the watch callback, the remote object must either wholly exist, in 00091 * which case the callback will be invoked, or have been destroyed, in 00092 * which case the callback will be ignored, and not be in some 00093 * transient half-state governed by another thread.) 00094 * 00095 * As mentioned above, the connected function encapsulated by the 00096 * callback passed to start_iowatch() must have a second (or only) 00097 * unbound bool& argument. If that bool& argument is set by the 00098 * connected function to false, say because end-of-file has been 00099 * reached, then the watch will be ended and all resources connected 00100 * with it deleted without further user action being required (there 00101 * is no need for the connected function to set it to true if the 00102 * watch is to continue, as that is the default). In addition, the 00103 * watch will be ended automatically and resources deleted if (i) as 00104 * mentioned above, the callback passed to start_iowatch() is 00105 * protected by a Releaser object and the target object whose method 00106 * is encapsulated by the callback is destroyed, or (ii) 00107 * g_source_remove() is called on the source id returned by 00108 * start_iowatch() (where the watch is attached to the default main 00109 * context) or g_source_destroy() is called on the GSource object 00110 * obtained from that id with g_main_context_find_source_by_id() 00111 * (where the watch has been attached to a non-default main context). 00112 * If the source has been removed automatically by virtue of the bool& 00113 * argument being set to false or by virtue of a Releaser object 00114 * releasing, g_source_remove() or g_source_destroy() should not 00115 * afterwards be called in respect of the id value returned by 00116 * start_iowatch() in case it has been reused by the main context 00117 * concerned in the meantime. 00118 */ 00119 00120 #include <glib.h> 00121 #include <c++-gtk-utils/callback.h> 00122 #include <c++-gtk-utils/cgu_config.h> 00123 00124 namespace Cgu { 00125 00126 class Releaser; 00127 00128 /** 00129 * Starts an io watch in the glib main loop on a file descriptor, and 00130 * executes the callback if the condition in io_condition is met. It 00131 * is thread-safe (it may be called in any thread) provided that, if 00132 * glib < 2.32 is used, g_thread_init() has been called. glib >= 2.32 00133 * does not require g_thread_init() to be called to be thread-safe. 00134 * @param fd The file descriptor. 00135 * @param cb The callback object. Ownership is taken of this object, 00136 * and it will be deleted when it has been finished with 00137 * @param io_condition The condition to be watched for (G_IO_IN may be 00138 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be 00139 * bitwise-ored with G_IO_ERR). 00140 * @param priority The priority to be given to the watch in the main 00141 * loop. In ascending order of priorities, priorities are 00142 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00143 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00144 * G_PRIORITY_DEFAULT. This determines the order in which the 00145 * callback will appear in the event list in the main loop, not the 00146 * priority which the OS will adopt 00147 * @param context The glib main context to which the watch is to be 00148 * attached (the default of NULL will cause the watch to be attached 00149 * to the main program loop, and this is almost always what is 00150 * wanted). 00151 * @return The glib source id of the watch. 00152 * @exception std::bad_alloc The method might throw std::bad_alloc if 00153 * memory is exhausted and the system throws in that case. If it does 00154 * so, the CallbackArg object will be disposed of. 00155 * @exception Cgu::Thread::MutexError This method might throw 00156 * Cgu:Thread::MutexError if initialisation of the mutex in a 00157 * SafeEmitterArg object constructed by this method fails. If it does 00158 * so, the CallbackArg object will be disposed of. (It is often not 00159 * worth checking for this exception, as it means either memory is 00160 * exhausted or pthread has run out of other resources to create new 00161 * mutexes.) 00162 * @note Cancellation of the thread to which the watch is attached is 00163 * blocked during execution of the callback. 00164 * @ingroup io_watch 00165 */ 00166 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, 00167 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00168 GMainContext* context = 0); 00169 00170 /** 00171 * Starts an io watch in the glib main loop on a file descriptor, and 00172 * executes the callback if the condition in io_condition is met. 00173 * This version provides for automatic watch disconnection when the 00174 * object whose function the callback represents is destroyed, via the 00175 * Releaser object. It is thread-safe (it may be called in any 00176 * thread) provided that, if glib < 2.32 is used, g_thread_init() has 00177 * been called. glib >= 2.32 does not require g_thread_init() to be 00178 * called to be thread-safe. 00179 * @param fd The file descriptor. 00180 * @param cb The callback object. Ownership is taken of this object, 00181 * and it will be deleted when it has been finished with. 00182 * @param r A Releaser object which the protected object has as a 00183 * public member. 00184 * @param io_condition The condition to be watched for (G_IO_IN may be 00185 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be 00186 * bitwise-ored with G_IO_ERR). 00187 * @param priority The priority to be given to the watch in the main 00188 * loop. In ascending order of priorities, priorities are 00189 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00190 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00191 * G_PRIORITY_DEFAULT. This determines the order in which the 00192 * callback will appear in the event list in the main loop, not the 00193 * priority which the OS will adopt 00194 * @param context The glib main context to which the watch is to be 00195 * attached (the default of NULL will cause the watch to be attached 00196 * to the main program loop, and this is almost always what is 00197 * wanted). 00198 * @return The glib source id of the watch. 00199 * @exception std::bad_alloc The method might throw std::bad_alloc if 00200 * memory is exhausted and the system throws in that case. If it does 00201 * so, the CallbackArg object will be disposed of. 00202 * @exception Cgu::Thread::MutexError This method might throw 00203 * Cgu:Thread::MutexError if initialisation of the mutex in a 00204 * SafeEmitterArg object constructed by this method fails. If it does 00205 * so, the CallbackArg object will be disposed of. (It is often not 00206 * worth checking for this exception, as it means either memory is 00207 * exhausted or pthread has run out of other resources to create new 00208 * mutexes.) 00209 * @note Cancellation of the thread to which the watch is attached is 00210 * blocked during execution of the callback. 00211 * @ingroup io_watch 00212 */ 00213 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, Releaser& r, 00214 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00215 GMainContext* context = 0); 00216 00217 /** 00218 * Starts an io watch in the glib main loop on a file descriptor, and 00219 * executes the callback if the condition in io_condition is met. 00220 * This version provides the GIOCondition status which caused the 00221 * callback to be invoked as the first unbound argument of the 00222 * callback object. It is thread-safe (it may be called in any 00223 * thread) provided that, if glib < 2.32 is used, g_thread_init() has 00224 * been called. glib >= 2.32 does not require g_thread_init() to be 00225 * called to be thread-safe. 00226 * @param fd The file descriptor. 00227 * @param cb The callback object. Ownership is taken of this object, 00228 * and it will be deleted when it has been finished with. 00229 * @param io_condition The condition(s) to be watched for (G_IO_IN, 00230 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored). 00231 * @param priority The priority to be given to the watch in the main 00232 * loop. In ascending order of priorities, priorities are 00233 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00234 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00235 * G_PRIORITY_DEFAULT. This determines the order in which the 00236 * callback will appear in the event list in the main loop, not the 00237 * priority which the OS will adopt 00238 * @param context The glib main context to which the watch is to be 00239 * attached (the default of NULL will cause the watch to be attached 00240 * to the main program loop, and this is almost always what is 00241 * wanted). 00242 * @return The glib source id of the watch. 00243 * @exception std::bad_alloc The method might throw std::bad_alloc if 00244 * memory is exhausted and the system throws in that case. If it does 00245 * so, the CallbackArg object will be disposed of. 00246 * @exception Cgu::Thread::MutexError This method might throw 00247 * Cgu:Thread::MutexError if initialisation of the mutex in a 00248 * SafeEmitterArg object constructed by this method fails. If it does 00249 * so, the CallbackArg object will be disposed of. (It is often not 00250 * worth checking for this exception, as it means either memory is 00251 * exhausted or pthread has run out of other resources to create new 00252 * mutexes.) 00253 * @note Cancellation of the thread to which the watch is attached is 00254 * blocked during execution of the callback. 00255 * @ingroup io_watch 00256 * 00257 * Since 2.0.0-rc2 00258 */ 00259 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb, 00260 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00261 GMainContext* context = 0); 00262 00263 /** 00264 * Starts an io watch in the glib main loop on a file descriptor, and 00265 * executes the callback if the condition in io_condition is met. 00266 * This version provides both automatic watch disconnection when the 00267 * object whose function the callback represents is destroyed, via the 00268 * Releaser object, and provides the GIOCondition status which caused 00269 * the callback to be invoked as the first unbound argument of the 00270 * callback object. It is thread-safe (it may be called in any 00271 * thread) provided that, if glib < 2.32 is used, g_thread_init() has 00272 * been called. glib >= 2.32 does not require g_thread_init() to be 00273 * called to be thread-safe. 00274 * @param fd The file descriptor. 00275 * @param cb The callback object. Ownership is taken of this object, 00276 * and it will be deleted when it has been finished with. 00277 * @param r A Releaser object which the protected object has as a 00278 * public member. 00279 * @param io_condition The condition(s) to be watched for (G_IO_IN, 00280 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored). 00281 * @param priority The priority to be given to the watch in the main 00282 * loop. In ascending order of priorities, priorities are 00283 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00284 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00285 * G_PRIORITY_DEFAULT. This determines the order in which the 00286 * callback will appear in the event list in the main loop, not the 00287 * priority which the OS will adopt 00288 * @param context The glib main context to which the watch is to be 00289 * attached (the default of NULL will cause the watch to be attached 00290 * to the main program loop, and this is almost always what is 00291 * wanted). 00292 * @return The glib source id of the watch. 00293 * @exception std::bad_alloc The method might throw std::bad_alloc if 00294 * memory is exhausted and the system throws in that case. If it does 00295 * so, the CallbackArg object will be disposed of. 00296 * @exception Cgu::Thread::MutexError This method might throw 00297 * Cgu:Thread::MutexError if initialisation of the mutex in a 00298 * SafeEmitterArg object constructed by this method fails. If it does 00299 * so, the CallbackArg object will be disposed of. (It is often not 00300 * worth checking for this exception, as it means either memory is 00301 * exhausted or pthread has run out of other resources to create new 00302 * mutexes.) 00303 * @note Cancellation of the thread to which the watch is attached is 00304 * blocked during execution of the callback. 00305 * @ingroup io_watch 00306 * 00307 * Since 2.0.0-rc2 00308 */ 00309 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb, 00310 Releaser& r, GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00311 GMainContext* context = 0); 00312 00313 } // namespace Cgu 00314 00315 #endif