* 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 "galias.h"
-#include "glib.h"
-
+#include "gqueue.h"
-G_LOCK_DEFINE_STATIC (queue_memchunk);
-static GMemChunk *queue_memchunk = NULL;
-static GTrashStack *free_queue_nodes = NULL;
+#include "gtestutils.h"
+#include "gslice.h"
/**
* g_queue_new:
*
- * Creates a new #GQueue.
+ * Creates a new #GQueue.
*
* Returns: a new #GQueue.
**/
GQueue*
g_queue_new (void)
{
- GQueue *queue;
-
- G_LOCK (queue_memchunk);
- queue = g_trash_stack_pop (&free_queue_nodes);
-
- if (!queue)
- {
- if (!queue_memchunk)
- queue_memchunk = g_mem_chunk_new ("GLib GQueue chunk",
- sizeof (GQueue),
- sizeof (GQueue) * 128,
- G_ALLOC_ONLY);
- queue = g_chunk_new (GQueue, queue_memchunk);
- }
- G_UNLOCK (queue_memchunk);
-
- queue->head = NULL;
- queue->tail = NULL;
- queue->length = 0;
-
- return queue;
+ return g_slice_new0 (GQueue);
}
/**
* g_queue_free:
* @queue: a #GQueue.
*
- * Frees the memory allocated for the #GQueue.
+ * 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)
g_return_if_fail (queue != NULL);
g_list_free (queue->head);
+ g_slice_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
+ *
+ * A statically-allocated #GQueue must be initialized with this function
+ * before it can be used. Alternatively you can initialize it with
+ * #G_QUEUE_INIT. It is not necessary to initialize queues created with
+ * g_queue_new().
+ *
+ * Since: 2.14
+ **/
+void
+g_queue_init (GQueue *queue)
+{
+ g_return_if_fail (queue != NULL);
+
+ queue->head = queue->tail = NULL;
+ queue->length = 0;
+}
-#ifdef ENABLE_GC_FRIENDLY
- queue->head = NULL;
- queue->tail = NULL;
-#endif /* ENABLE_GC_FRIENDLY */
+/**
+ * g_queue_clear:
+ * @queue: a #GQueue
+ *
+ * Removes all the elements in @queue. If queue elements contain
+ * dynamically-allocated memory, they should be freed first.
+ *
+ * Since: 2.14
+ */
+void
+g_queue_clear (GQueue *queue)
+{
+ g_return_if_fail (queue != NULL);
- G_LOCK (queue_memchunk);
- g_trash_stack_push (&free_queue_nodes, queue);
- G_UNLOCK (queue_memchunk);
+ g_list_free (queue->head);
+ g_queue_init (queue);
}
/**
* Finds an element in a #GQueue, using a supplied function to find the
* desired element. It iterates over the queue, calling the given function
* which should return 0 when the desired element is found. The function
- * takes two gconstpointer arguments, the #GQueue element's data and the
- * given user data.
+ * takes two gconstpointer arguments, the #GQueue element's data as the
+ * first argument and the given user data as the second argument.
*
* Return value: The found link, or %NULL if it wasn't found
*
/**
* g_queue_link_index:
- * @queue: a #Gqueue
+ * @queue: a #GQueue
* @link_: A #GList link
*
* Returns the position of @link_ in @queue.
}
/**
- * g_queue_unlink
+ * g_queue_unlink:
* @queue: a #GQueue
* @link_: a #GList link that <emphasis>must</emphasis> be part of @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);
}
/**
* @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)
list = next;
}
+
+ return (old_length - queue->length);
}
/**
* called with two elements of the @queue and @user_data. It should
* return 0 if the elements are equal, a negative value if the first
* element comes before the second, and a positive value if the second
- * element comes after the first.
+ * element comes before the first.
* @user_data: user data passed to @func.
*
* Inserts @data into @queue using @func to determine the new position.
projects / platform / upstream / glib.git / blobdiff