Add full variant to the approximate timeout functiont

The g_timeout_add_seconds() API lacks a _full() counterpart, allowing the
setting of a destroy notification function to be invoked when the timeout
source is removed.

This patch adds g_timeout_add_seconds_full() to the public API and
reimplements g_timeout_add_seconds() as a call to g_timeout_add_seconds_full().

svn path=/trunk/; revision=5575

ChangeLog

@@ -1,3 +1,11 @@
+2007-06-18  Emmanuele Bassi  <ebassi@gnome.org>
+
+	* glib/gmain.h:
+	* glib/gmain.c:
+	* glib/glib.symbols: Add g_timeout_add_seconds_full() variant
+	to g_timeout_add_seconds(), accepting a destroy notification
+	function and a priority. (#448819)
+
 2007-06-17  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/gutils (g_get_current_dir): Prevent segfaults on

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2007-06-18  Emmanuele Bassi  <ebassi@gnome.org>
+
+	* glib/glib-sections.txt: Add g_timeout_add_seconds_full().
+
 2007-06-17  Behdad Esfahbod  <behdad@gnome.org>
 
 	* glib/tmpl/quarks.sgml:

docs/reference/glib/glib-sections.txt

@@ -442,6 +442,7 @@ g_timeout_source_new_seconds
 g_timeout_add
 g_timeout_add_full
 g_timeout_add_seconds
+g_timeout_add_seconds_full
 
 <SUBSECTION>
 g_idle_source_new

glib/glib.symbols

@@ -622,6 +622,7 @@ g_idle_source_new
 g_timeout_add
 g_timeout_add_seconds
 g_timeout_add_full
+g_timeout_add_seconds_full
 g_timeout_source_new
 g_timeout_source_new_seconds
 #endif

glib/gmain.c

@@ -3560,13 +3560,13 @@ g_timeout_source_new_seconds (guint interval)
 
 /**
  * g_timeout_add_full:
- * @priority: the priority of the idle source. Typically this will be in the
+ * @priority: the priority of the timeout source. Typically this will be in
- *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
+ *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
  * @interval: the time between calls to the function, in milliseconds
  *             (1/1000ths of a second)
  * @function: function to call
  * @data:     data to pass to @function
- * @notify:   function to call when the idle is removed, or %NULL
+ * @notify:   function to call when the timeout is removed, or %NULL
  * 
  * Sets a function to be called at regular intervals, with the given
  * priority.  The function is called repeatedly until it returns
@@ -3643,15 +3643,18 @@ g_timeout_add (guint32        interval,
 }
 
 /**
- * g_timeout_add_seconds:
+ * g_timeout_add_seconds_full:
+ * @priority: the priority of the timeout source. Typically this will be in
+ *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
  * @interval: the time between calls to the function, in seconds
  * @function: function to call
  * @data:     data to pass to @function
+ * @notify:   function to call when the timeout is removed, or %NULL
  *
- * Sets a function to be called at regular intervals, with the default
+ * Sets a function to be called at regular intervals, with @priority.
- * priority, #G_PRIORITY_DEFAULT.  The function is called repeatedly
+ * The function is called repeatedly until it returns %FALSE, at which
- * until it returns %FALSE, at which point the timeout is automatically
+ * point the timeout is automatically destroyed and the function will
- * destroyed and the function will not be called again.
+ * not be called again.
  *
  * Unlike g_timeout_add(), this function operates at whole second granularity.
  * The initial starting point of the timer is determined by the implementation
@@ -3679,9 +3682,11 @@ g_timeout_add (guint32        interval,
  * Since: 2.14
  **/
 guint
-g_timeout_add_seconds (guint32        interval,
+g_timeout_add_seconds_full (gint           priority,
-	       GSourceFunc    function,
+                            guint32        interval,
-	       gpointer       data)
+                            GSourceFunc    function,
+                            gpointer       data,
+                            GDestroyNotify notify)
 {
   GSource *source;
   guint id;
@@ -3690,13 +3695,43 @@ g_timeout_add_seconds (guint32        interval,
 
   source = g_timeout_source_new_seconds (interval);
 
-  g_source_set_callback (source, function, data, NULL);
+  if (priority != G_PRIORITY_DEFAULT)
+    g_source_set_priority (source, priority);
+
+  g_source_set_callback (source, function, data, notify);
   id = g_source_attach (source, NULL);
   g_source_unref (source);
 
   return id;
 }
 
+/**
+ * g_timeout_add_seconds:
+ * @interval: the time between calls to the function, in seconds
+ * @function: function to call
+ * @data: data to pass to @function
+ *
+ * Sets a function to be called at regular intervals with the default
+ * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
+ * it returns %FALSE, at which point the timeout is automatically destroyed
+ * and the function will not be called again.
+ *
+ * See g_timeout_add_seconds_full() for the differences between
+ * g_timeout_add() and g_timeout_add_seconds().
+ *
+ * Return value: the ID (greater than 0) of the event source.
+ *
+ * Since: 2.14
+ **/
+guint
+g_timeout_add_seconds (guint       interval,
+                       GSourceFunc function,
+                       gpointer    data)
+{
+  g_return_val_if_fail (function != NULL, 0);
+
+  return g_timeout_add_seconds_full (G_PRIORITY_DEFAULT, interval, function, data, NULL);
+}
 
 /* Child watch functions */
 

glib/gmain.h

@@ -295,32 +295,37 @@ gboolean g_source_remove_by_funcs_user_data  (GSourceFuncs  *funcs,
 					      gpointer       user_data);
 
 /* Idles, child watchers and timeouts */
-guint    g_timeout_add_full     (gint            priority,
+guint    g_timeout_add_full         (gint            priority,
-				 guint           interval,
+				     guint           interval,
-				 GSourceFunc     function,
+				     GSourceFunc     function,
-				 gpointer        data,
+				     gpointer        data,
-				 GDestroyNotify  notify);
+				     GDestroyNotify  notify);
-guint    g_timeout_add          (guint           interval,
+guint    g_timeout_add              (guint           interval,
-				 GSourceFunc     function,
+				     GSourceFunc     function,
-				 gpointer        data);
+				     gpointer        data);
-guint    g_timeout_add_seconds  (guint           interval,
+guint    g_timeout_add_seconds_full (gint            priority,
-				 GSourceFunc     function,
+                                     guint           interval,
-				 gpointer        data);
+                                     GSourceFunc     function,
-guint    g_child_watch_add_full (gint            priority,
+                                     gpointer        data,
-				 GPid            pid,
+                                     GDestroyNotify  notify);
-				 GChildWatchFunc function,
+guint    g_timeout_add_seconds      (guint           interval,
-				 gpointer        data,
+				     GSourceFunc     function,
-				 GDestroyNotify  notify);
+				     gpointer        data);
-guint    g_child_watch_add      (GPid            pid,
+guint    g_child_watch_add_full     (gint            priority,
-				 GChildWatchFunc function,
+				     GPid            pid,
-				 gpointer        data);
+				     GChildWatchFunc function,
-guint    g_idle_add             (GSourceFunc     function,
+				     gpointer        data,
-				 gpointer        data);
+				     GDestroyNotify  notify);
-guint    g_idle_add_full        (gint            priority,
+guint    g_child_watch_add          (GPid            pid,
-				 GSourceFunc     function,
+				     GChildWatchFunc function,
-				 gpointer        data,
+				     gpointer        data);
-				 GDestroyNotify  notify);
+guint    g_idle_add                 (GSourceFunc     function,
-gboolean g_idle_remove_by_data  (gpointer        data);
+				     gpointer        data);
+guint    g_idle_add_full            (gint            priority,
+				     GSourceFunc     function,
+				     gpointer        data,
+				     GDestroyNotify  notify);
+gboolean g_idle_remove_by_data      (gpointer        data);
 
 /* Hook for GClosure / GSource integration. Don't touch */
 GLIB_VAR GSourceFuncs g_timeout_funcs;