Add some mainloop instrumentation

[platform/upstream/glib.git] / glib / gqueue.c

diff --git a/glib/gqueue.c b/glib/gqueue.c
index 0100870..64117eb 100644 (file)
--- a/glib/gqueue.c
+++ b/glib/gqueue.c
@@ -24,14 +24,42 @@
  * MT safe
  */
 
+/**
+ * SECTION:queue
+ * @Title: Double-ended Queues
+ * @Short_description: double-ended queue data structure
+ *
+ * The #GQueue structure and its associated functions provide a standard
+ * queue data structure. Internally, GQueue uses the same data structure
+ * as #GList to store elements.
+ *
+ * The data contained in each element can be either integer values, by
+ * using one of the <link linkend="glib-Type-Conversion-Macros">Type
+ * Conversion Macros</link>, or simply pointers to any type of data.
+ *
+ * To create a new GQueue, use g_queue_new().
+ *
+ * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
+ * g_queue_init().
+ *
+ * To add elements, use g_queue_push_head(), g_queue_push_head_link(),
+ * g_queue_push_tail() and g_queue_push_tail_link().
+ *
+ * To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
+ *
+ * To free the entire queue, use g_queue_free().
+ */
 #include "config.h"
 
-#include "glib.h"
+#include "gqueue.h"
+
+#include "gtestutils.h"
+#include "gslice.h"
 
 /**
  * g_queue_new:
  *
- * Creates a new #GQueue. 
+ * Creates a new #GQueue.
  *
  * Returns: a new #GQueue.
  **/
@@ -48,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)
@@ -59,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
  *
@@ -722,7 +774,7 @@ g_queue_peek_nth_link (GQueue *queue,
 
 /**
  * g_queue_link_index:
- * @queue: a #Gqueue
+ * @queue: a #GQueue
  * @link_: A #GList link
  * 
  * Returns the position of @link_ in @queue.
@@ -742,7 +794,7 @@ g_queue_link_index (GQueue *queue,
 }
 
 /**
- * g_queue_unlink
+ * g_queue_unlink:
  * @queue: a #GQueue
  * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue
  *
@@ -878,20 +930,24 @@ g_queue_index (GQueue        *queue,
  * 
  * Removes the first element in @queue that contains @data. 
  * 
+ * Return value: %TRUE if @data was found and removed from @queue
+ *
  * Since: 2.4
  **/
-void
+gboolean
 g_queue_remove (GQueue        *queue,
                gconstpointer  data)
 {
   GList *link;
   
-  g_return_if_fail (queue != NULL);
+  g_return_val_if_fail (queue != NULL, FALSE);
 
   link = g_list_find (queue->head, data);
 
   if (link)
     g_queue_delete_link (queue, link);
+
+  return (link != NULL);
 }
 
 /**
@@ -899,17 +955,22 @@ g_queue_remove (GQueue        *queue,
  * @queue: a #GQueue
  * @data: data to remove
  * 
- * Remove all elemeents in @queue which contains @data.
+ * Remove all elements whose data equals @data from @queue.
  * 
+ * Return value: the number of elements removed from @queue
+ *
  * Since: 2.4
  **/
-void
+guint
 g_queue_remove_all (GQueue        *queue,
                    gconstpointer  data)
 {
   GList *list;
+  guint old_length;
   
-  g_return_if_fail (queue != NULL);
+  g_return_val_if_fail (queue != NULL, 0);
+
+  old_length = queue->length;
 
   list = queue->head;
   while (list)
@@ -921,6 +982,8 @@ g_queue_remove_all (GQueue        *queue,
       
       list = next;
     }
+
+  return (old_length - queue->length);
 }
 
 /**