[evolution-data-server] Add macros/functions to help name timeouts.

[Matthew Barnes <mbarnes src gnome org>]

commit 7280d882f99076ba9a0ab7375806f7aad77d3d66
Author: Matthew Barnes <mbarnes redhat com>
Date:   Tue Oct 29 11:37:47 2013 -0400

    Add macros/functions to help name timeouts.
    
    The macros form a name for the timeout GSource implicitly.
    
    New macros:
    
      e_named_timeout_add()
      e_named_timeout_add_full()
      e_named_timeout_add_seconds()
      e_named_timeout_add_seconds_full()
    
    New functions (called by the macros):
    
      e_timeout_add_with_name()
      e_timeout_add_seconds_with_name()

 .../libedataserver/libedataserver-sections.txt     |    6 +
 libedataserver/e-data-server-util.c                |  150 ++++++++++++++++++++
 libedataserver/e-data-server-util.h                |  101 +++++++++++++
 3 files changed, 257 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/libedataserver/libedataserver-sections.txt 
b/docs/reference/libedataserver/libedataserver-sections.txt
index 8dc97f9..c18665d 100644
--- a/docs/reference/libedataserver/libedataserver-sections.txt
+++ b/docs/reference/libedataserver/libedataserver-sections.txt
@@ -1335,6 +1335,12 @@ e_named_parameters_set
 e_named_parameters_get
 e_named_parameters_to_strv
 e_named_parameters_test
+e_named_timeout_add
+e_named_timeout_add_full
+e_named_timeout_add_seconds
+e_named_timeout_add_seconds_full
+e_timeout_add_with_name
+e_timeout_add_seconds_with_name
 <SUBSECTION Deprecated>
 e_util_free_string_slist
 e_util_free_object_slist
diff --git a/libedataserver/e-data-server-util.c b/libedataserver/e-data-server-util.c
index 4c90452..ba792d2 100644
--- a/libedataserver/e-data-server-util.c
+++ b/libedataserver/e-data-server-util.c
@@ -2107,3 +2107,153 @@ G_DEFINE_BOXED_TYPE (
        e_named_parameters,
        e_named_parameters_ref,
        e_named_parameters_unref);
+
+/**
+ * e_named_timeout_add:
+ * @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
+ *
+ * Similar to g_timeout_add(), but also names the #GSource for use in
+ * debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definintion from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+
+/**
+ * e_named_timeout_add_full:
+ * @priority: the priority of the timeout source, typically in 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 timeout is removed, or %NULL
+ *
+ * Similar to g_timeout_add_full(), but also names the #GSource for use
+ * in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+
+/**
+ * e_named_timeout_add_seconds:
+ * @interval: the time between calls to the function, in seconds
+ * @function: function to call
+ * @data: data to pass to @function
+ *
+ * Similar to g_timeout_add_seconds(), but also names the #GSource for use
+ * in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+
+/**
+ * e_named_timeout_add_seconds_full:
+ * @priority: the priority of the timeout source, typically 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
+ *
+ * Similar to g_timeout_add_seconds_full(), but also names the #GSource for
+ * use in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+
+/**
+ * e_timeout_add_with_name:
+ * @priority: the priority of the timeout source, typically in 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)
+ * @name: (allow-none): debug name for the source
+ * @function: function to call
+ * @data: data to pass to @function
+ * @notify: (allow-none): function to call when the timeout is removed,
+ *          or %NULL
+ *
+ * Similar to g_timeout_add_full(), but also names the #GSource as @name.
+ *
+ * You might find e_named_timeout_add() or e_named_timeout_add_full() more
+ * convenient.  Those macros name the #GSource implicitly.
+ *
+ * Returns: the ID (greather than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+guint
+e_timeout_add_with_name (gint priority,
+                         guint interval,
+                         const gchar *name,
+                         GSourceFunc function,
+                         gpointer data,
+                         GDestroyNotify notify)
+{
+       guint tag;
+
+       g_return_val_if_fail (function != NULL, 0);
+
+       tag = g_timeout_add_full (
+               priority, interval, function, data, notify);
+       g_source_set_name_by_id (tag, name);
+
+       return tag;
+}
+
+/**
+ * e_timeout_add_seconds_with_name:
+ * @priority: the priority of the timeout source, typically in the
+ *            range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH
+ * @interval: the time between calls to the function, in seconds
+ * @name: (allow-none): debug name for the source
+ * @function: function to call
+ * @data: data to pass to @function
+ * @notify: (allow-none): function to call when the timeout is removed,
+ *          or %NULL
+ *
+ * Similar to g_timeout_add_seconds_full(), but also names the #GSource as
+ * %name.
+ *
+ * You might find e_named_timeout_add_seconds() or
+ * e_named_timeout_add_seconds_full() more convenient.  Those macros name
+ * the #GSource implicitly.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+guint
+e_timeout_add_seconds_with_name (gint priority,
+                                 guint interval,
+                                 const gchar *name,
+                                 GSourceFunc function,
+                                 gpointer data,
+                                 GDestroyNotify notify)
+{
+       guint tag;
+
+       g_return_val_if_fail (function != NULL, 0);
+
+       tag = g_timeout_add_seconds_full (
+               priority, interval, function, data, notify);
+       g_source_set_name_by_id (tag, name);
+
+       return tag;
+}
+
diff --git a/libedataserver/e-data-server-util.h b/libedataserver/e-data-server-util.h
index 154ca57..ebb96db 100644
--- a/libedataserver/e-data-server-util.h
+++ b/libedataserver/e-data-server-util.h
@@ -163,6 +163,107 @@ gboolean  e_named_parameters_test         (const ENamedParameters *parameters,
                                                 const gchar *value,
                                                 gboolean case_sensitively);
 
+/**
+ * e_named_timeout_add:
+ * @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
+ *
+ * Similar to g_timeout_add(), but also names the #GSource for use in
+ * debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definintion from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+#define e_named_timeout_add(interval, function, data) \
+       (e_timeout_add_with_name ( \
+               G_PRIORITY_DEFAULT, (interval), \
+               "[" PACKAGE "] " G_STRINGIFY (function), \
+               (function), (data), NULL))
+
+/**
+ * e_named_timeout_add_full:
+ * @priority: the priority of the timeout source, typically in 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 timeout is removed, or %NULL
+ *
+ * Similar to g_timeout_add_full(), but also names the #GSource for use
+ * in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+#define e_named_timeout_add_full(priority, interval, function, data, notify) \
+       (e_timeout_add_with_name ( \
+               (priority), (interval), \
+               "[" PACKAGE "] " G_STRINGIFY (function), \
+               (function), (data), (notify))
+
+/**
+ * e_named_timeout_add_seconds:
+ * @interval: the time between calls to the function, in seconds
+ * @function: function to call
+ * @data: data to pass to @function
+ *
+ * Similar to g_timeout_add_seconds(), but also names the #GSource for use
+ * in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+#define e_named_timeout_add_seconds(interval, function, data) \
+       (e_timeout_add_seconds_with_name ( \
+               G_PRIORITY_DEFAULT, (interval), \
+               "[" PACKAGE "] " G_STRINGIFY (function), \
+               (function), (data), NULL))
+
+/**
+ * e_named_timeout_add_seconds_full:
+ * @priority: the priority of the timeout source, typically 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
+ *
+ * Similar to g_timeout_add_seconds_full(), but also names the #GSource for
+ * use in debugging and profiling.  The name is formed from @function and the
+ * <literal>PACKAGE</literal> definition from a &lt;config.h&gt; file.
+ *
+ * Returns: the ID (greater than 0) of the event source
+ *
+ * Since: 3.12
+ **/
+#define e_named_timeout_add_seconds_full(priority, interval, function, data, notify) \
+       (e_timeout_add_seconds_with_name ( \
+               (priority), (interval), \
+               "[" PACKAGE "] " G_STRINGIFY (function), \
+               (function), (data), (notify))
+
+guint          e_timeout_add_with_name         (gint priority,
+                                                guint interval,
+                                                const gchar *name,
+                                                GSourceFunc function,
+                                                gpointer data,
+                                                GDestroyNotify notify);
+guint          e_timeout_add_seconds_with_name (gint priority,
+                                                guint interval,
+                                                const gchar *name,
+                                                GSourceFunc function,
+                                                gpointer data,
+                                                GDestroyNotify notify);
+
 #ifndef EDS_DISABLE_DEPRECATED
 void           e_util_free_string_slist        (GSList *strings);
 void           e_util_free_object_slist        (GSList *objects);