c++-gtk-utils
io_watch.h
Go to the documentation of this file.
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