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