[glib] Added API g_queue_free_full().

[Matthias Clasen <matthiasc src gnome org>]

commit 1d4009e6f7e1d368b3e3df2fa41b007277b600d8
Author: Ravi Sankar Guntur <ravi g samsung com>
Date:   Wed Dec 14 20:17:54 2011 +0530

    Added API g_queue_free_full().
    
    g_queue_free_full(), to free a Queue including its dynamically-allocated elements.
    On similar lines to List and Slist.
    
    void  g_queue_free_full  (GQueue  *queue,  GDestroyNotify    free_func);
    
    Test case covering g_queue_free_full() is added.
    Added export symbol to glib.symbols.
    
    Closes Bug: https://bugzilla.gnome.org/show_bug.cgi?id=657433
    
    Signed-off-by: Ravi Sankar Guntur <ravi g samsung com>

 glib/glib.symbols  |    1 +
 glib/gqueue.c      |   24 ++++++++++++++++++++++++
 glib/gqueue.h      |    2 ++
 glib/tests/queue.c |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 77 insertions(+), 0 deletions(-)
---
diff --git a/glib/glib.symbols b/glib/glib.symbols
index 15d6616..e914e86 100644
--- a/glib/glib.symbols
+++ b/glib/glib.symbols
@@ -810,6 +810,7 @@ g_queue_find
 g_queue_find_custom
 g_queue_foreach
 g_queue_free
+g_queue_free_full
 g_queue_get_length
 g_queue_index
 g_queue_init
diff --git a/glib/gqueue.c b/glib/gqueue.c
index 8d01b86..d9ee3a8 100644
--- a/glib/gqueue.c
+++ b/glib/gqueue.c
@@ -76,6 +76,12 @@ g_queue_new (void)
  * Frees the memory allocated for the #GQueue. Only call this function if
  * @queue was created with g_queue_new(). If queue elements contain
  * dynamically-allocated memory, they should be freed first.
+ *
+ * <note><para>
+ * If queue elements contain dynamically-allocated memory,
+ * you should either use g_queue_free_full() or free them manually
+ * first.
+ * </para></note>
  **/
 void
 g_queue_free (GQueue *queue)
@@ -87,6 +93,24 @@ g_queue_free (GQueue *queue)
 }
 
 /**
+ * g_queue_free_full:
+ * @queue: a pointer to a #GQueue
+ * @free_func: the function to be called to free each element's data
+ *
+ * Convenience method, which frees all the memory used by a #GQueue, and
+ * calls the specified destroy function on every element's data.
+ *
+ * Since: 2.32
+ */
+void
+g_queue_free_full (GQueue         *queue,
+		  GDestroyNotify  free_func)
+{
+  g_queue_foreach (queue, (GFunc) free_func, NULL);
+  g_queue_free (queue);
+}
+
+/**
  * g_queue_init:
  * @queue: an uninitialized #GQueue
  *
diff --git a/glib/gqueue.h b/glib/gqueue.h
index dd236d5..1d13eef 100644
--- a/glib/gqueue.h
+++ b/glib/gqueue.h
@@ -73,6 +73,8 @@ struct _GQueue
  */
 GQueue*  g_queue_new            (void);
 void     g_queue_free           (GQueue           *queue);
+void     g_queue_free_full      (GQueue           *queue,
+				GDestroyNotify    free_func);
 void     g_queue_init           (GQueue           *queue);
 void     g_queue_clear          (GQueue           *queue);
 gboolean g_queue_is_empty       (GQueue           *queue);
diff --git a/glib/tests/queue.c b/glib/tests/queue.c
index 3aeea56..e2593a4 100644
--- a/glib/tests/queue.c
+++ b/glib/tests/queue.c
@@ -1028,6 +1028,55 @@ test_clear (void)
   g_queue_free (q);
 }
 
+typedef struct
+{
+  gboolean freed;
+  int x;
+} QueueItem;
+
+static void
+free_func (gpointer data)
+{
+  QueueItem *item = data;
+
+  item->freed = TRUE;
+}
+
+static QueueItem *
+new_item (int x)
+{
+  QueueItem *item;
+
+  item = g_slice_new (QueueItem);
+  item->freed = FALSE;
+  item->x = x;
+
+  return item;
+}
+
+static void
+test_free_full (void)
+{
+  QueueItem *one, *two, *three;
+  GQueue *queue = NULL;
+
+  queue = g_queue_new();
+  g_queue_push_tail (queue, one = new_item (1));
+  g_queue_push_tail (queue, two = new_item (2));
+  g_queue_push_tail (queue, three = new_item (3));
+  g_assert (!one->freed);
+  g_assert (!two->freed);
+  g_assert (!three->freed);
+  g_queue_free_full (queue, free_func);
+  g_assert (one->freed);
+  g_assert (two->freed);
+  g_assert (three->freed);
+  g_slice_free (QueueItem, one);
+  g_slice_free (QueueItem, two);
+  g_slice_free (QueueItem, three);
+}
+
+
 int main (int argc, char *argv[])
 {
   guint32 seed;
@@ -1041,6 +1090,7 @@ int main (int argc, char *argv[])
   g_test_add_func ("/queue/find-custom", test_find_custom);
   g_test_add_func ("/queue/static", test_static);
   g_test_add_func ("/queue/clear", test_clear);
+  g_test_add_func ("/queue/free-full", test_free_full);
 
   seed = g_test_rand_int_range (0, G_MAXINT);
   path = g_strdup_printf ("/queue/random/seed:%u", seed);