1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * GAsyncQueue: asynchronous queue implementation, based on Gqueue.
5 * Copyright (C) 2000 Sebastian Wilhelmi; University of Karlsruhe
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
38 guint waiting_threads;
45 * Creates a new asynchronous queue with the initial reference count of 1.
47 * Return value: the new #GAsyncQueue.
52 GAsyncQueue* retval = g_new (GAsyncQueue, 1);
53 retval->mutex = g_mutex_new ();
55 retval->queue = g_queue_new ();
56 retval->waiting_threads = 0;
57 retval->ref_count = 1;
63 * @queue: a #GAsyncQueue.
65 * Increases the reference count of the asynchronous @queue by 1. You
66 * do not need to hold the lock to call this function.
69 g_async_queue_ref (GAsyncQueue *queue)
71 g_return_if_fail (queue);
72 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
74 g_atomic_int_inc (&queue->ref_count);
78 * g_async_queue_ref_unlocked:
79 * @queue: a #GAsyncQueue.
81 * Increases the reference count of the asynchronous @queue by 1.
84 g_async_queue_ref_unlocked (GAsyncQueue *queue)
86 g_return_if_fail (queue);
87 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
89 g_atomic_int_inc (&queue->ref_count);
93 * g_async_queue_unref_and_unlock:
94 * @queue: a #GAsyncQueue.
96 * Decreases the reference count of the asynchronous @queue by 1 and
97 * releases the lock. This function must be called while holding the
98 * @queue's lock. If the reference count went to 0, the @queue will be
99 * destroyed and the memory allocated will be freed.
102 g_async_queue_unref_and_unlock (GAsyncQueue *queue)
104 g_return_if_fail (queue);
105 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
107 g_mutex_unlock (queue->mutex);
108 g_async_queue_unref (queue);
112 * g_async_queue_unref:
113 * @queue: a #GAsyncQueue.
115 * Decreases the reference count of the asynchronous @queue by 1. If
116 * the reference count went to 0, the @queue will be destroyed and the
117 * memory allocated will be freed. So you are not allowed to use the
118 * @queue afterwards, as it might have disappeared. You do not need to
119 * hold the lock to call this function.
122 g_async_queue_unref (GAsyncQueue *queue)
124 g_return_if_fail (queue);
125 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
127 if (g_atomic_int_dec_and_test (&queue->ref_count))
129 g_return_if_fail (queue->waiting_threads == 0);
130 g_mutex_free (queue->mutex);
132 g_cond_free (queue->cond);
133 g_queue_free (queue->queue);
139 * g_async_queue_lock:
140 * @queue: a #GAsyncQueue.
142 * Acquires the @queue's lock. After that you can only call the
143 * <function>g_async_queue_*_unlocked()</function> function variants on that
144 * @queue. Otherwise it will deadlock.
147 g_async_queue_lock (GAsyncQueue *queue)
149 g_return_if_fail (queue);
150 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
152 g_mutex_lock (queue->mutex);
156 * g_async_queue_unlock:
157 * @queue: a #GAsyncQueue.
159 * Releases the queue's lock.
162 g_async_queue_unlock (GAsyncQueue *queue)
164 g_return_if_fail (queue);
165 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
167 g_mutex_unlock (queue->mutex);
171 * g_async_queue_push:
172 * @queue: a #GAsyncQueue.
173 * @data: @data to push into the @queue.
175 * Pushes the @data into the @queue. @data must not be %NULL.
178 g_async_queue_push (GAsyncQueue* queue, gpointer data)
180 g_return_if_fail (queue);
181 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
182 g_return_if_fail (data);
184 g_mutex_lock (queue->mutex);
185 g_async_queue_push_unlocked (queue, data);
186 g_mutex_unlock (queue->mutex);
190 * g_async_queue_push_unlocked:
191 * @queue: a #GAsyncQueue.
192 * @data: @data to push into the @queue.
194 * Pushes the @data into the @queue. @data must not be %NULL. This
195 * function must be called while holding the @queue's lock.
198 g_async_queue_push_unlocked (GAsyncQueue* queue, gpointer data)
200 g_return_if_fail (queue);
201 g_return_if_fail (g_atomic_int_get (&queue->ref_count) > 0);
202 g_return_if_fail (data);
204 g_queue_push_head (queue->queue, data);
205 if (queue->waiting_threads > 0)
206 g_cond_signal (queue->cond);
210 g_async_queue_pop_intern_unlocked (GAsyncQueue* queue, gboolean try,
215 if (!g_queue_peek_tail (queue->queue))
221 queue->cond = g_cond_new ();
225 queue->waiting_threads++;
226 while (!g_queue_peek_tail (queue->queue))
227 g_cond_wait(queue->cond, queue->mutex);
228 queue->waiting_threads--;
232 queue->waiting_threads++;
233 while (!g_queue_peek_tail (queue->queue))
234 if (!g_cond_timed_wait (queue->cond, queue->mutex, end_time))
236 queue->waiting_threads--;
237 if (!g_queue_peek_tail (queue->queue))
242 retval = g_queue_pop_tail (queue->queue);
251 * @queue: a #GAsyncQueue.
253 * Pops data from the @queue. This function blocks until data become
256 * Return value: data from the queue.
259 g_async_queue_pop (GAsyncQueue* queue)
263 g_return_val_if_fail (queue, NULL);
264 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
266 g_mutex_lock (queue->mutex);
267 retval = g_async_queue_pop_intern_unlocked (queue, FALSE, NULL);
268 g_mutex_unlock (queue->mutex);
274 * g_async_queue_pop_unlocked:
275 * @queue: a #GAsyncQueue.
277 * Pops data from the @queue. This function blocks until data become
278 * available. This function must be called while holding the @queue's
281 * Return value: data from the queue.
284 g_async_queue_pop_unlocked (GAsyncQueue* queue)
286 g_return_val_if_fail (queue, NULL);
287 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
289 return g_async_queue_pop_intern_unlocked (queue, FALSE, NULL);
293 * g_async_queue_try_pop:
294 * @queue: a #GAsyncQueue.
296 * Tries to pop data from the @queue. If no data is available, %NULL is
299 * Return value: data from the queue or %NULL, when no data is
300 * available immediately.
303 g_async_queue_try_pop (GAsyncQueue* queue)
307 g_return_val_if_fail (queue, NULL);
308 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
310 g_mutex_lock (queue->mutex);
311 retval = g_async_queue_pop_intern_unlocked (queue, TRUE, NULL);
312 g_mutex_unlock (queue->mutex);
318 * g_async_queue_try_pop_unlocked:
319 * @queue: a #GAsyncQueue.
321 * Tries to pop data from the @queue. If no data is available, %NULL is
322 * returned. This function must be called while holding the @queue's
325 * Return value: data from the queue or %NULL, when no data is
326 * available immediately.
329 g_async_queue_try_pop_unlocked (GAsyncQueue* queue)
331 g_return_val_if_fail (queue, NULL);
332 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
334 return g_async_queue_pop_intern_unlocked (queue, TRUE, NULL);
338 * g_async_queue_timed_pop:
339 * @queue: a #GAsyncQueue.
340 * @end_time: a #GTimeVal, determining the final time.
342 * Pops data from the @queue. If no data is received before @end_time,
345 * To easily calculate @end_time a combination of g_get_current_time()
346 * and g_time_val_add() can be used.
348 * Return value: data from the queue or %NULL, when no data is
349 * received before @end_time.
352 g_async_queue_timed_pop (GAsyncQueue* queue, GTimeVal *end_time)
356 g_return_val_if_fail (queue, NULL);
357 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
359 g_mutex_lock (queue->mutex);
360 retval = g_async_queue_pop_intern_unlocked (queue, FALSE, end_time);
361 g_mutex_unlock (queue->mutex);
367 * g_async_queue_timed_pop_unlocked:
368 * @queue: a #GAsyncQueue.
369 * @end_time: a #GTimeVal, determining the final time.
371 * Pops data from the @queue. If no data is received before @end_time,
372 * %NULL is returned. This function must be called while holding the
375 * To easily calculate @end_time a combination of g_get_current_time()
376 * and g_time_val_add() can be used.
378 * Return value: data from the queue or %NULL, when no data is
379 * received before @end_time.
382 g_async_queue_timed_pop_unlocked (GAsyncQueue* queue, GTimeVal *end_time)
384 g_return_val_if_fail (queue, NULL);
385 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, NULL);
387 return g_async_queue_pop_intern_unlocked (queue, FALSE, end_time);
391 * g_async_queue_length:
392 * @queue: a #GAsyncQueue.
394 * Returns the length of the queue, negative values mean waiting
395 * threads, positive values mean available entries in the
396 * @queue. Actually this function returns the number of data items in
397 * the queue minus the number of waiting threads. Thus a return value
398 * of 0 could mean 'n' entries in the queue and 'n' thread waiting.
399 * That can happen due to locking of the queue or due to
402 * Return value: the length of the @queue.
405 g_async_queue_length (GAsyncQueue* queue)
409 g_return_val_if_fail (queue, 0);
410 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, 0);
412 g_mutex_lock (queue->mutex);
413 retval = queue->queue->length - queue->waiting_threads;
414 g_mutex_unlock (queue->mutex);
420 * g_async_queue_length_unlocked:
421 * @queue: a #GAsyncQueue.
423 * Returns the length of the queue, negative values mean waiting
424 * threads, positive values mean available entries in the
425 * @queue. Actually this function returns the number of data items in
426 * the queue minus the number of waiting threads. Thus a return value
427 * of 0 could mean 'n' entries in the queue and 'n' thread waiting.
428 * That can happen due to locking of the queue or due to
429 * scheduling. This function must be called while holding the @queue's
432 * Return value: the length of the @queue.
435 g_async_queue_length_unlocked (GAsyncQueue* queue)
437 g_return_val_if_fail (queue, 0);
438 g_return_val_if_fail (g_atomic_int_get (&queue->ref_count) > 0, 0);
440 return queue->queue->length - queue->waiting_threads;