[glib/wip/source-api: 3/5] GSource: make 'prepare' and 'check' optional

[Ryan Lortie <ryanl src gnome org>]

commit e4c4f38b4575deb3438dcbf319c198da43c0fee8
Author: Ryan Lortie <desrt desrt ca>
Date:   Tue Aug 30 19:13:37 2011 -0400

    GSource: make 'prepare' and 'check' optional
    
    Make the 'prepare' and 'check' GSourceFuncs optional -- in fact,
    suggest against using them.

 glib/gmain.c |   37 ++++++++++++++++++++++---------------
 glib/gmain.h |   32 +++++++++++++++++++++-----------
 2 files changed, 43 insertions(+), 26 deletions(-)
---
diff --git a/glib/gmain.c b/glib/gmain.c
index 05df57d..e15db72 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -2692,18 +2692,22 @@ g_main_context_prepare (GMainContext *context,
 
       if (!(source->flags & G_SOURCE_READY))
 	{
-	  gboolean result;
+	  gboolean result = FALSE;
 	  gboolean (*prepare)  (GSource  *source, 
 				gint     *timeout);
 
 	  prepare = source->source_funcs->prepare;
-	  context->in_check_or_prepare++;
-	  UNLOCK_CONTEXT (context);
 
-	  result = (*prepare) (source, &source_timeout);
+          if (prepare != NULL)
+            {
+              context->in_check_or_prepare++;
+              UNLOCK_CONTEXT (context);
+
+              result = (*prepare) (source, &source_timeout);
 
-	  LOCK_CONTEXT (context);
-	  context->in_check_or_prepare--;
+              LOCK_CONTEXT (context);
+              context->in_check_or_prepare--;
+            }
 
           if (result == FALSE && source->priv->ready_time != -1)
             {
@@ -2904,18 +2908,21 @@ g_main_context_check (GMainContext *context,
 
       if (!(source->flags & G_SOURCE_READY))
 	{
-	  gboolean result;
+	  gboolean result = FALSE;
 	  gboolean (*check) (GSource  *source);
 
 	  check = source->source_funcs->check;
-	  
-	  context->in_check_or_prepare++;
-	  UNLOCK_CONTEXT (context);
-	  
-	  result = (*check) (source);
-	  
-	  LOCK_CONTEXT (context);
-	  context->in_check_or_prepare--;
+
+          if (check != NULL)
+            {
+              context->in_check_or_prepare++;
+              UNLOCK_CONTEXT (context);
+
+              result = (*check) (source);
+
+              LOCK_CONTEXT (context);
+              context->in_check_or_prepare--;
+            }
 
           if (result == FALSE && source->priv->ready_time != -1)
             {
diff --git a/glib/gmain.h b/glib/gmain.h
index 9640653..71692d0 100644
--- a/glib/gmain.h
+++ b/glib/gmain.h
@@ -69,17 +69,27 @@ typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
 
 /**
  * GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the
- *     source can determine that it is ready here (without waiting for the
- *     results of the poll() call) it should return %TRUE. It can also return
- *     a @timeout_ value which should be the maximum timeout (in milliseconds)
- *     which should be passed to the poll() call. The actual timeout used will
- *     be -1 if all sources returned -1, or it will be the minimum of all the
- *     @timeout_ values returned which were >= 0.
- * @check: Called after all the file descriptors are polled. The source
- *     should return %TRUE if it is ready to be dispatched. Note that some
- *     time may have passed since the previous prepare function was called,
- *     so the source should be checked again here.
+ * @prepare: Should be %NULL in most cases.  This field allows the
+ *     source to provide a function to manually control the length of
+ *     time that the g_poll() call is given as a timeout.  If set, the
+ *     function is called before all the file descriptors are polled. If
+ *     the source can determine that it is ready here (without waiting
+ *     for the results of the poll() call) it should return %TRUE. It
+ *     can also return a @timeout_ value which should be the maximum
+ *     timeout (in milliseconds) which should be passed to the poll()
+ *     call. The actual timeout used will be -1 if all sources returned
+ *     -1, or it will be the minimum of all the @timeout_ values
+ *     returned which were >= 0.  This may be %NULL, in which case the
+ *     effect is as if the function always returns %FALSE with @timeout_
+ *     set to -1.
+ * @check: Should be %NULL in most cases.  This field allows the source
+ *     to provide a function to override the default semantics of being
+ *     considered as ready when any of its file descritors poll as
+ *     ready.  If set, it is called after all the file descriptors are
+ *     polled.  The source should return %TRUE if it is ready to be
+ *     dispatched.  Note that some time may have passed since the
+ *     previous prepare function was called, so the source should be
+ *     checked again here.
  * @dispatch: Called to dispatch the event source, after it has returned
  *     %TRUE in either its @prepare or its @check function. The @dispatch
  *     function is passed in a callback function and data. The callback