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