c++-gtk-utils
|
00001 /* Copyright (C) 2005 to 2011 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 59 Temple Place - Suite 330, Boston, MA, 02111-1307, 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 the glib main loop has been made thread-safe by a 00078 * call to g_thread_init(). 00079 * 00080 * start_iowatch() takes ownership of the passed Callback object. Two 00081 * of the four start_iowatch() overloads take a Callback::Releaser 00082 * object as their third argument, which provides for automatic 00083 * ceasing of the watch if the target object which has the Releaser as 00084 * a member is destroyed. (Note that for this to be race free, the 00085 * lifetime of the remote target object whose method is to be invoked 00086 * must be determined by the thread to whose main loop the watch has 00087 * been attached. When the main loop begins invoking the execution of 00088 * the watch callback, the remote object must either wholly exist, in 00089 * which case the callback will be invoked, or have been destroyed, in 00090 * which case the callback will be ignored, and not be in some 00091 * transient half-state governed by another thread.) 00092 * 00093 * As mentioned above, the connected function encapsulated by the 00094 * callback passed to start_iowatch() must have a second (or only) 00095 * unbound bool& argument. If that bool& argument is set by the 00096 * connected function to false, say because end-of-file has been 00097 * reached, then the watch will be ended and all resources connected 00098 * with it deleted without further user action being required (there 00099 * is no need for the connected function to set it to true if the 00100 * watch is to continue, as that is the default). In addition, the 00101 * watch will be ended automatically and resources deleted if (i) as 00102 * mentioned above, the callback passed to start_iowatch() is 00103 * protected by a Releaser object and the target object whose method 00104 * is encapsulated by the callback is destroyed, or (ii) 00105 * g_source_remove() is called on the source id returned by 00106 * start_iowatch() (where the watch is attached to the default main 00107 * context) or g_source_destroy() is called on the GSource object 00108 * obtained from that id with g_main_context_find_source_by_id() 00109 * (where the watch has been attached to a non-default main context). 00110 * If the source has been removed automatically by virtue of the bool& 00111 * argument being set to false or by virtue of a Releaser object 00112 * releasing, g_source_remove() or g_source_destroy() should not 00113 * afterwards be called in respect of the id value returned by 00114 * start_iowatch() in case it has been reused by the main context 00115 * concerned in the meantime. 00116 */ 00117 00118 #include <glib.h> 00119 #include <c++-gtk-utils/callback.h> 00120 #include <c++-gtk-utils/cgu_config.h> 00121 00122 namespace Cgu { 00123 00124 class Releaser; 00125 00126 /** 00127 * Starts an io watch in the glib main loop on a file descriptor, and 00128 * executes the callback if the condition in io_condition is met. It 00129 * is thread-safe (it may be called in any thread) provided that the 00130 * glib main loop has been made thread-safe by a call to 00131 * g_thread_init(). 00132 * @param fd The file descriptor. 00133 * @param cb The callback object. Ownership is taken of this object, 00134 * and it will be deleted when it has been finished with 00135 * @param io_condition The condition to be watched for (G_IO_IN may be 00136 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be 00137 * bitwise-ored with G_IO_ERR). 00138 * @param priority The priority to be given to the watch in the main 00139 * loop. In ascending order of priorities, priorities are 00140 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00141 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00142 * G_PRIORITY_DEFAULT. This determines the order in which the 00143 * callback will appear in the event list in the main loop, not the 00144 * priority which the OS will adopt 00145 * @param context The glib main context to which the watch is to be 00146 * attached (the default of NULL will cause the watch to be attached 00147 * to the main program loop, and this is almost always what is 00148 * wanted). 00149 * @return The glib source id of the watch. 00150 * @exception std::bad_alloc The method might throw std::bad_alloc if 00151 * memory is exhausted and the system throws in that case. If it does 00152 * so, the CallbackArg object will be disposed of. 00153 * @exception Cgu::Thread::MutexError This method might throw 00154 * Cgu:Thread::MutexError if initialisation of the mutex in a 00155 * SafeEmitterArg object constructed by this method fails. If it does 00156 * so, the CallbackArg object will be disposed of. (It is often not 00157 * worth checking for this exception, as it means either memory is 00158 * exhausted or pthread has run out of other resources to create new 00159 * mutexes.) 00160 * @note Cancellation of the thread to which the watch is attached is 00161 * blocked during execution of the callback. 00162 * @ingroup io_watch 00163 */ 00164 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, 00165 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00166 GMainContext* context = 0); 00167 00168 /** 00169 * Starts an io watch in the glib main loop on a file descriptor, and 00170 * executes the callback if the condition in io_condition is met. 00171 * This version provides for automatic watch disconnection when the 00172 * object whose function the callback represents is destroyed, via the 00173 * Releaser object. It is thread-safe (it may be called in any 00174 * thread) provided that the glib main loop has been made thread-safe 00175 * by a call to g_thread_init(). 00176 * @param fd The file descriptor. 00177 * @param cb The callback object. Ownership is taken of this object, 00178 * and it will be deleted when it has been finished with. 00179 * @param r A Releaser object which the protected object has as a 00180 * public member. 00181 * @param io_condition The condition to be watched for (G_IO_IN may be 00182 * bitwise-ored with G_IO_HUP, and G_IO_IN and G_IO_OUT may be 00183 * bitwise-ored with G_IO_ERR). 00184 * @param priority The priority to be given to the watch in the main 00185 * loop. In ascending order of priorities, priorities are 00186 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00187 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00188 * G_PRIORITY_DEFAULT. This determines the order in which the 00189 * callback will appear in the event list in the main loop, not the 00190 * priority which the OS will adopt 00191 * @param context The glib main context to which the watch is to be 00192 * attached (the default of NULL will cause the watch to be attached 00193 * to the main program loop, and this is almost always what is 00194 * wanted). 00195 * @return The glib source id of the watch. 00196 * @exception std::bad_alloc The method might throw std::bad_alloc if 00197 * memory is exhausted and the system throws in that case. If it does 00198 * so, the CallbackArg object will be disposed of. 00199 * @exception Cgu::Thread::MutexError This method might throw 00200 * Cgu:Thread::MutexError if initialisation of the mutex in a 00201 * SafeEmitterArg object constructed by this method fails. If it does 00202 * so, the CallbackArg object will be disposed of. (It is often not 00203 * worth checking for this exception, as it means either memory is 00204 * exhausted or pthread has run out of other resources to create new 00205 * mutexes.) 00206 * @note Cancellation of the thread to which the watch is attached is 00207 * blocked during execution of the callback. 00208 * @ingroup io_watch 00209 */ 00210 guint start_iowatch(int fd, const Callback::CallbackArg<bool&>* cb, Releaser& r, 00211 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00212 GMainContext* context = 0); 00213 00214 /** 00215 * Starts an io watch in the glib main loop on a file descriptor, and 00216 * executes the callback if the condition in io_condition is met. 00217 * This version provides the GIOCondition status which caused the 00218 * callback to be invoked as the first unbound argument of the 00219 * callback object. It is thread-safe (it may be called in any 00220 * thread) provided that the glib main loop has been made thread-safe 00221 * by a call to g_thread_init(). 00222 * @param fd The file descriptor. 00223 * @param cb The callback object. Ownership is taken of this object, 00224 * and it will be deleted when it has been finished with. 00225 * @param io_condition The condition(s) to be watched for (G_IO_IN, 00226 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored). 00227 * @param priority The priority to be given to the watch in the main 00228 * loop. In ascending order of priorities, priorities are 00229 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00230 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00231 * G_PRIORITY_DEFAULT. This determines the order in which the 00232 * callback will appear in the event list in the main loop, not the 00233 * priority which the OS will adopt 00234 * @param context The glib main context to which the watch is to be 00235 * attached (the default of NULL will cause the watch to be attached 00236 * to the main program loop, and this is almost always what is 00237 * wanted). 00238 * @return The glib source id of the watch. 00239 * @exception std::bad_alloc The method might throw std::bad_alloc if 00240 * memory is exhausted and the system throws in that case. If it does 00241 * so, the CallbackArg object will be disposed of. 00242 * @exception Cgu::Thread::MutexError This method might throw 00243 * Cgu:Thread::MutexError if initialisation of the mutex in a 00244 * SafeEmitterArg object constructed by this method fails. If it does 00245 * so, the CallbackArg object will be disposed of. (It is often not 00246 * worth checking for this exception, as it means either memory is 00247 * exhausted or pthread has run out of other resources to create new 00248 * mutexes.) 00249 * @note Cancellation of the thread to which the watch is attached is 00250 * blocked during execution of the callback. 00251 * @ingroup io_watch 00252 * 00253 * Since 2.0.0-rc2 00254 */ 00255 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb, 00256 GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00257 GMainContext* context = 0); 00258 00259 /** 00260 * Starts an io watch in the glib main loop on a file descriptor, and 00261 * executes the callback if the condition in io_condition is met. 00262 * This version provides both automatic watch disconnection when the 00263 * object whose function the callback represents is destroyed, via the 00264 * Releaser object, and provides the GIOCondition status which caused 00265 * the callback to be invoked as the first unbound argument of the 00266 * callback object. It is thread-safe (it may be called in any 00267 * thread) provided that the glib main loop has been made thread-safe 00268 * by a call to g_thread_init(). 00269 * @param fd The file descriptor. 00270 * @param cb The callback object. Ownership is taken of this object, 00271 * and it will be deleted when it has been finished with. 00272 * @param r A Releaser object which the protected object has as a 00273 * public member. 00274 * @param io_condition The condition(s) to be watched for (G_IO_IN, 00275 * G_IO_OUT, G_IO_HUP and G_IO_ERR may all be bitwise-ored). 00276 * @param priority The priority to be given to the watch in the main 00277 * loop. In ascending order of priorities, priorities are 00278 * G_PRIORITY_LOW, G_PRIORITY_DEFAULT_IDLE, G_PRIORITY_HIGH_IDLE, 00279 * G_PRIORITY_DEFAULT and G_PRIORITY_HIGH. The default is 00280 * G_PRIORITY_DEFAULT. This determines the order in which the 00281 * callback will appear in the event list in the main loop, not the 00282 * priority which the OS will adopt 00283 * @param context The glib main context to which the watch is to be 00284 * attached (the default of NULL will cause the watch to be attached 00285 * to the main program loop, and this is almost always what is 00286 * wanted). 00287 * @return The glib source id of the watch. 00288 * @exception std::bad_alloc The method might throw std::bad_alloc if 00289 * memory is exhausted and the system throws in that case. If it does 00290 * so, the CallbackArg object will be disposed of. 00291 * @exception Cgu::Thread::MutexError This method might throw 00292 * Cgu:Thread::MutexError if initialisation of the mutex in a 00293 * SafeEmitterArg object constructed by this method fails. If it does 00294 * so, the CallbackArg object will be disposed of. (It is often not 00295 * worth checking for this exception, as it means either memory is 00296 * exhausted or pthread has run out of other resources to create new 00297 * mutexes.) 00298 * @note Cancellation of the thread to which the watch is attached is 00299 * blocked during execution of the callback. 00300 * @ingroup io_watch 00301 * 00302 * Since 2.0.0-rc2 00303 */ 00304 guint start_iowatch(int fd, const Callback::CallbackArg<GIOCondition, bool&>* cb, 00305 Releaser& r, GIOCondition io_condition, gint priority = G_PRIORITY_DEFAULT, 00306 GMainContext* context = 0); 00307 00308 } // namespace Cgu 00309 00310 #endif