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