From cc3e80c26a7ff2612ec78d483c7b32b293e14dd1 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Tue, 6 Mar 2007 18:43:10 +0000 Subject: [PATCH] Add G_QUEUE_INIT, g_queue_init(), and g_queue_clear() to better support 2007-03-06 Matthew Barnes * glib/gqueue.h: * glib/gqueue.c: Add G_QUEUE_INIT, g_queue_init(), and g_queue_clear() to better support statically allocated queues. (#413244) svn path=/trunk/; revision=5378 --- ChangeLog | 7 +++++ docs/reference/glib/glib-sections.txt | 3 ++ docs/reference/glib/tmpl/queue.sgml | 36 +++++++++++++++++++++++ glib/glib.symbols | 2 ++ glib/gqueue.c | 42 ++++++++++++++++++++++++++- glib/gqueue.h | 4 +++ 6 files changed, 93 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index f7d837c9f..94032400b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2007-03-06 Matthew Barnes + + * glib/gqueue.h: + * glib/gqueue.c: Add G_QUEUE_INIT, g_queue_init(), and + g_queue_clear() to better support statically allocated + queues. (#413244) + 2007-03-06 Matthias Clasen * glib/gkeyfile.c (g_key_file_parse_value_as_boolean): diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index cd6d354a3..83a1e27ca 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -1785,6 +1785,9 @@ g_slist_pop_allocator GQueue g_queue_new g_queue_free +G_QUEUE_INIT +g_queue_init +g_queue_clear g_queue_is_empty g_queue_get_length g_queue_reverse diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index 44e262091..688357d4b 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/docs/reference/glib/tmpl/queue.sgml @@ -20,6 +20,10 @@ 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(). @@ -63,6 +67,38 @@ Contains the public fields of a Queue. @queue: + + +A statically-allocated #GQueue must be initialized with this macro before it +can be used. This macro can be used to initialize a variable, but it cannot +be assigned to a variable. In that case you have to use g_queue_init(). + + + + +GQueue my_queue = G_QUEUE_INIT; + + + +@Since: 2.14 + + + + + + + +@queue: + + + + + + + +@queue: + + diff --git a/glib/glib.symbols b/glib/glib.symbols index 034021565..820ec56a1 100644 --- a/glib/glib.symbols +++ b/glib/glib.symbols @@ -821,6 +821,7 @@ g_qsort_with_data #if IN_HEADER(__G_QUEUE_H__) #if IN_FILE(__G_QUEUE_C__) +g_queue_clear g_queue_copy g_queue_delete_link g_queue_find @@ -829,6 +830,7 @@ g_queue_foreach g_queue_free g_queue_get_length g_queue_index +g_queue_init g_queue_insert_after g_queue_insert_before g_queue_insert_sorted diff --git a/glib/gqueue.c b/glib/gqueue.c index f381db380..1368e2614 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -46,7 +46,9 @@ g_queue_new (void) * 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. **/ void g_queue_free (GQueue *queue) @@ -57,6 +59,44 @@ g_queue_free (GQueue *queue) g_slice_free (GQueue, 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; +} + +/** + * 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_list_free (queue->head); + g_queue_init (queue); +} + /** * g_queue_is_empty: * @queue: a #GQueue. diff --git a/glib/gqueue.h b/glib/gqueue.h index 36810ff88..c4004514d 100644 --- a/glib/gqueue.h +++ b/glib/gqueue.h @@ -40,10 +40,14 @@ struct _GQueue guint length; }; +#define G_QUEUE_INIT { NULL, NULL, 0 } + /* Queues */ GQueue* g_queue_new (void); void g_queue_free (GQueue *queue); +void g_queue_init (GQueue *queue); +void g_queue_clear (GQueue *queue); gboolean g_queue_is_empty (GQueue *queue); guint g_queue_get_length (GQueue *queue); void g_queue_reverse (GQueue *queue);