gst/gstatomicqueue.c

   1 /* GStreamer
   2  * Copyright (C) 2009 Edward Hervey <bilboed@bilboed.com>
   3  *               2011 Wim Taymans <wim.taymans@gmail.com>
   4  *
   5  * gstatomicqueue.c:
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library 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.
  11  *
  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  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library 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.
  21  */
  22
  23 #include "gst_private.h"
  24
  25 #include <string.h>
  26
  27 #include <gst/gst.h>
  28 #include "gstatomicqueue.h"
  29
  30 /**
  31  * SECTION:gstatomicqueue
  32  * @title: GstAtomicQueue
  33  * @short_description: An atomic queue implementation
  34  *
  35  * The #GstAtomicQueue object implements a queue that can be used from multiple
  36  * threads without performing any blocking operations.
  37  *
  38  * Since: 0.10.33
  39  */
  40
  41 /* By default the queue uses 2 * sizeof(gpointer) * clp2 (max_items) of
  42  * memory. clp2(x) is the next power of two >= than x.
  43  *
  44  * The queue can operate in low memory mode, in which it consumes almost
  45  * half the memory at the expense of extra overhead in the readers. This
  46  * is disabled by default because even without LOW_MEM mode, the memory
  47  * consumption is still lower than a plain GList.
  48  */
  49 #undef LOW_MEM
  50
  51 typedef struct _GstAQueueMem GstAQueueMem;
  52
  53 struct _GstAQueueMem
  54 {
  55   gint size;
  56   gpointer *array;
  57   volatile gint head;
  58   volatile gint tail;
  59   GstAQueueMem *next;
  60   GstAQueueMem *free;
  61 };
  62
  63 static guint
  64 clp2 (guint n)
  65 {
  66   guint res = 1;
  67
  68   while (res < n)
  69     res <<= 1;
  70
  71   return res;
  72 }
  73
  74 static GstAQueueMem *
  75 new_queue_mem (guint size, gint pos)
  76 {
  77   GstAQueueMem *mem;
  78
  79   mem = g_new (GstAQueueMem, 1);
  80
  81   /* we keep the size as a mask for performance */
  82   mem->size = clp2 (MAX (size, 16)) - 1;
  83   mem->array = g_new0 (gpointer, mem->size + 1);
  84   mem->head = pos;
  85   mem->tail = pos;
  86   mem->next = NULL;
  87   mem->free = NULL;
  88
  89   return mem;
  90 }
  91
  92 static void
  93 free_queue_mem (GstAQueueMem * mem)
  94 {
  95   g_free (mem->array);
  96   g_free (mem);
  97 }
  98
  99 struct _GstAtomicQueue
 100 {
 101   volatile gint refcount;
 102 #ifdef LOW_MEM
 103   gint num_readers;
 104 #endif
 105   GstAQueueMem *head_mem;
 106   GstAQueueMem *tail_mem;
 107   GstAQueueMem *free_list;
 108 };
 109
 110 static void
 111 add_to_free_list (GstAtomicQueue * queue, GstAQueueMem * mem)
 112 {
 113   do {
 114     mem->free = g_atomic_pointer_get (&queue->free_list);
 115   } while (!g_atomic_pointer_compare_and_exchange ((gpointer *) &
 116           queue->free_list, mem->free, mem));
 117 }
 118
 119 static void
 120 clear_free_list (GstAtomicQueue * queue)
 121 {
 122   GstAQueueMem *free_list;
 123
 124   /* take the free list and replace with NULL */
 125   do {
 126     free_list = g_atomic_pointer_get (&queue->free_list);
 127     if (free_list == NULL)
 128       return;
 129   } while (!g_atomic_pointer_compare_and_exchange ((gpointer *) &
 130           queue->free_list, free_list, NULL));
 131
 132   while (free_list) {
 133     GstAQueueMem *next = free_list->free;
 134
 135     free_queue_mem (free_list);
 136
 137     free_list = next;
 138   }
 139 }
 140
 141 /**
 142  * gst_atomic_queue_new:
 143  * @initial_size: initial queue size
 144  *
 145  * Create a new atomic queue instance. @initial_size will be rounded up to the
 146  * nearest power of 2 and used as the initial size of the queue.
 147  *
 148  * Returns: a new #GstAtomicQueue
 149  *
 150  * Since: 0.10.33
 151  */
 152 GstAtomicQueue *
 153 gst_atomic_queue_new (guint initial_size)
 154 {
 155   GstAtomicQueue *queue;
 156
 157   queue = g_new (GstAtomicQueue, 1);
 158
 159   queue->refcount = 1;
 160 #ifdef LOW_MEM
 161   queue->num_readers = 0;
 162 #endif
 163   queue->head_mem = queue->tail_mem = new_queue_mem (initial_size, 0);
 164   queue->free_list = NULL;
 165
 166   return queue;
 167 }
 168
 169 /**
 170  * gst_atomic_queue_ref:
 171  * @queue: a #GstAtomicQueue
 172  *
 173  * Increase the refcount of @queue.
 174  *
 175  * Since: 0.10.33
 176  */
 177 void
 178 gst_atomic_queue_ref (GstAtomicQueue * queue)
 179 {
 180   g_return_if_fail (queue != NULL);
 181
 182   g_atomic_int_inc (&queue->refcount);
 183 }
 184
 185 static void
 186 gst_atomic_queue_free (GstAtomicQueue * queue)
 187 {
 188   free_queue_mem (queue->head_mem);
 189   if (queue->head_mem != queue->tail_mem)
 190     free_queue_mem (queue->tail_mem);
 191   clear_free_list (queue);
 192   g_free (queue);
 193 }
 194
 195 /**
 196  * gst_atomic_queue_unref:
 197  * @queue: a #GstAtomicQueue
 198  *
 199  * Unref @queue and free the memory when the refcount reaches 0.
 200  *
 201  * Since: 0.10.33
 202  */
 203 void
 204 gst_atomic_queue_unref (GstAtomicQueue * queue)
 205 {
 206   g_return_if_fail (queue != NULL);
 207
 208   if (g_atomic_int_dec_and_test (&queue->refcount))
 209     gst_atomic_queue_free (queue);
 210 }
 211
 212 /**
 213  * gst_atomic_queue_peek:
 214  * @queue: a #GstAtomicQueue
 215  *
 216  * Peek the head element of the queue without removing it from the queue.
 217  *
 218  * Returns: the head element of @queue or NULL when the queue is empty.
 219  *
 220  * Since: 0.10.33
 221  */
 222 gpointer
 223 gst_atomic_queue_peek (GstAtomicQueue * queue)
 224 {
 225   GstAQueueMem *head_mem;
 226   gint head, tail, size;
 227
 228   g_return_val_if_fail (queue != NULL, NULL);
 229
 230   while (TRUE) {
 231     GstAQueueMem *next;
 232
 233     head_mem = g_atomic_pointer_get (&queue->head_mem);
 234
 235     head = g_atomic_int_get (&head_mem->head);
 236     tail = g_atomic_int_get (&head_mem->tail);
 237     size = head_mem->size;
 238
 239     /* when we are not empty, we can continue */
 240     if (G_LIKELY (head != tail))
 241       break;
 242
 243     /* else array empty, try to take next */
 244     next = g_atomic_pointer_get (&head_mem->next);
 245     if (next == NULL)
 246       return NULL;
 247
 248     /* now we try to move the next array as the head memory. If we fail to do that,
 249      * some other reader managed to do it first and we retry */
 250     if (!g_atomic_pointer_compare_and_exchange ((gpointer *) &
 251             queue->head_mem, head_mem, next))
 252       continue;
 253
 254     /* when we managed to swing the head pointer the old head is now
 255      * useless and we add it to the freelist. We can't free the memory yet
 256      * because we first need to make sure no reader is accessing it anymore. */
 257     add_to_free_list (queue, head_mem);
 258   }
 259
 260   return head_mem->array[head & size];
 261 }
 262
 263 /**
 264  * gst_atomic_queue_pop:
 265  * @queue: a #GstAtomicQueue
 266  *
 267  * Get the head element of the queue.
 268  *
 269  * Returns: the head element of @queue or NULL when the queue is empty.
 270  *
 271  * Since: 0.10.33
 272  */
 273 gpointer
 274 gst_atomic_queue_pop (GstAtomicQueue * queue)
 275 {
 276   gpointer ret;
 277   GstAQueueMem *head_mem;
 278   gint head, tail, size;
 279
 280   g_return_val_if_fail (queue != NULL, NULL);
 281
 282 #ifdef LOW_MEM
 283   g_atomic_int_inc (&queue->num_readers);
 284 #endif
 285
 286   do {
 287     while (TRUE) {
 288       GstAQueueMem *next;
 289
 290       head_mem = g_atomic_pointer_get (&queue->head_mem);
 291
 292       head = g_atomic_int_get (&head_mem->head);
 293       tail = g_atomic_int_get (&head_mem->tail);
 294       size = head_mem->size;
 295
 296       /* when we are not empty, we can continue */
 297       if (G_LIKELY (head != tail))
 298         break;
 299
 300       /* else array empty, try to take next */
 301       next = g_atomic_pointer_get (&head_mem->next);
 302       if (next == NULL)
 303         return NULL;
 304
 305       /* now we try to move the next array as the head memory. If we fail to do that,
 306        * some other reader managed to do it first and we retry */
 307       if (!g_atomic_pointer_compare_and_exchange ((gpointer *) &
 308               queue->head_mem, head_mem, next))
 309         continue;
 310
 311       /* when we managed to swing the head pointer the old head is now
 312        * useless and we add it to the freelist. We can't free the memory yet
 313        * because we first need to make sure no reader is accessing it anymore. */
 314       add_to_free_list (queue, head_mem);
 315     }
 316
 317     ret = head_mem->array[head & size];
 318   } while (!g_atomic_int_compare_and_exchange (&head_mem->head, head,
 319           head + 1));
 320
 321 #ifdef LOW_MEM
 322   /* decrement number of readers, when we reach 0 readers we can be sure that
 323    * none is accessing the memory in the free list and we can try to clean up */
 324   if (g_atomic_int_dec_and_test (&queue->num_readers))
 325     clear_free_list (queue);
 326 #endif
 327
 328   return ret;
 329 }
 330
 331 /**
 332  * gst_atomic_queue_push:
 333  * @queue: a #GstAtomicQueue
 334  * @data: the data
 335  *
 336  * Append @data to the tail of the queue.
 337  *
 338  * Since: 0.10.33
 339  */
 340 void
 341 gst_atomic_queue_push (GstAtomicQueue * queue, gpointer data)
 342 {
 343   GstAQueueMem *tail_mem;
 344   gint head, tail, size;
 345
 346   g_return_if_fail (queue != NULL);
 347
 348   do {
 349     while (TRUE) {
 350       GstAQueueMem *mem;
 351
 352       tail_mem = g_atomic_pointer_get (&queue->tail_mem);
 353       head = g_atomic_int_get (&tail_mem->head);
 354       tail = g_atomic_int_get (&tail_mem->tail);
 355       size = tail_mem->size;
 356
 357       /* we're not full, continue */
 358       if (tail - head <= size)
 359         break;
 360
 361       /* else we need to grow the array, we store a mask so we have to add 1 */
 362       mem = new_queue_mem ((size << 1) + 1, tail);
 363
 364       /* try to make our new array visible to other writers */
 365       if (!g_atomic_pointer_compare_and_exchange ((gpointer *) &
 366               queue->tail_mem, tail_mem, mem)) {
 367         /* we tried to swap the new writer array but something changed. This is
 368          * because some other writer beat us to it, we free our memory and try
 369          * again */
 370         free_queue_mem (mem);
 371         continue;
 372       }
 373       /* make sure that readers can find our new array as well. The one who
 374        * manages to swap the pointer is the only one who can set the next
 375        * pointer to the new array */
 376       g_atomic_pointer_set (&tail_mem->next, mem);
 377     }
 378   } while (!g_atomic_int_compare_and_exchange (&tail_mem->tail, tail,
 379           tail + 1));
 380
 381   tail_mem->array[tail & size] = data;
 382 }
 383
 384 /**
 385  * gst_atomic_queue_length:
 386  * @queue: a #GstAtomicQueue
 387  *
 388  * Get the amount of items in the queue.
 389  *
 390  * Returns: the number of elements in the queue.
 391  *
 392  * Since: 0.10.33
 393  */
 394 guint
 395 gst_atomic_queue_length (GstAtomicQueue * queue)
 396 {
 397   GstAQueueMem *head_mem, *tail_mem;
 398   gint head, tail;
 399
 400   g_return_val_if_fail (queue != NULL, 0);
 401
 402 #ifdef LOW_MEM
 403   g_atomic_int_inc (&queue->num_readers);
 404 #endif
 405
 406   head_mem = g_atomic_pointer_get (&queue->head_mem);
 407   head = g_atomic_int_get (&head_mem->head);
 408
 409   tail_mem = g_atomic_pointer_get (&queue->tail_mem);
 410   tail = g_atomic_int_get (&tail_mem->tail);
 411
 412 #ifdef LOW_MEM
 413   if (g_atomic_int_dec_and_test (&queue->num_readers))
 414     clear_free_list (queue);
 415 #endif
 416
 417   return tail - head;
 418 }