text: /* GStreamer
   * Copyright (C) 2009 Edward Hervey <bilboed@bilboed.com>
   *               2011 Wim Taymans <wim.taymans@gmail.com>
   *
   * gstatomicqueue.c:
   *
   * This library is free software; you can redistribute it and/or
   * modify it under the terms of the GNU Library General Public
   * License as published by the Free Software Foundation; either
   * version 2 of the License, or (at your option) any later version.
   *
   * This library is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   * Library General Public License for more details.
   *
   * You should have received a copy of the GNU Library General Public
   * License along with this library; if not, write to the
   * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
   * Boston, MA 02110-1301, USA.
   */
  
  #include "gst_private.h"
  
  #include <string.h>
  
  #include <gst/gst.h>
  #include "gstatomicqueue.h"
  #include "glib-compat-private.h"
  
  /**
   * SECTION:gstatomicqueue
   * @title: GstAtomicQueue
   * @short_description: An atomic queue implementation
   *
   * The #GstAtomicQueue object implements a queue that can be used from multiple
   * threads without performing any blocking operations.
   */
  
  G_DEFINE_BOXED_TYPE (GstAtomicQueue, gst_atomic_queue,
      (GBoxedCopyFunc) gst_atomic_queue_ref,
      (GBoxedFreeFunc) gst_atomic_queue_unref);
  
  /* By default the queue uses 2 * sizeof(gpointer) * clp2 (max_items) of
   * memory. clp2(x) is the next power of two >= than x.
   *
   * The queue can operate in low memory mode, in which it consumes almost
   * half the memory at the expense of extra overhead in the readers. This
   * is disabled by default because even without LOW_MEM mode, the memory
   * consumption is still lower than a plain GList.
   */
  #undef LOW_MEM
  
  typedef struct _GstAQueueMem GstAQueueMem;
  
  struct _GstAQueueMem
  {
    gint size;
    gpointer *array;
    volatile gint head;
    volatile gint tail_write;
    volatile gint tail_read;
    GstAQueueMem *next;
    GstAQueueMem *free;
  };
  
  static guint
  clp2 (guint n)
  {
    guint res = 1;
  
    while (res < n)
      res <<= 1;
  
    return res;
  }
  
  static GstAQueueMem *
  new_queue_mem (guint size, gint pos)
  {
    GstAQueueMem *mem;
  
    mem = g_new (GstAQueueMem, 1);
  
    /* we keep the size as a mask for performance */
    mem->size = clp2 (MAX (size, 16)) - 1;
    mem->array = g_new0 (gpointer, mem->size + 1);
    mem->head = pos;
    mem->tail_write = pos;
    mem->tail_read = pos;
    mem->next = NULL;
    mem->free = NULL;
  
    return mem;
  }
  
  static void
  free_queue_mem (GstAQueueMem * mem)
  {
    g_free (mem->array);
    g_free (mem);
  }
  
  struct _GstAtomicQueue
  {
    volatile gint refcount;
  #ifdef LOW_MEM
    gint num_readers;
  #endif
    GstAQueueMem *head_mem;
    GstAQueueMem *tail_mem;
    GstAQueueMem *free_list;
  };
  
  static void
  add_to_free_list (GstAtomicQueue * queue, GstAQueueMem * mem)
  {
    do {
      mem->free = g_atomic_pointer_get (&queue->free_list);
    } while (!g_atomic_pointer_compare_and_exchange (&queue->free_list,
            mem->free, mem));
  }
  
  static void
  clear_free_list (GstAtomicQueue * queue)
  {
    GstAQueueMem *free_list;
  
    /* take the free list and replace with NULL */
    do {
      free_list = g_atomic_pointer_get (&queue->free_list);
      if (free_list == NULL)
        return;
    } while (!g_atomic_pointer_compare_and_exchange (&queue->free_list, free_list,
            NULL));
  
    while (free_list) {
      GstAQueueMem *next = free_list->free;
  
      free_queue_mem (free_list);
  
      free_list = next;
    }
  }
  
  /**
   * gst_atomic_queue_new:
   * @initial_size: initial queue size
   *
   * Create a new atomic queue instance. @initial_size will be rounded up to the
   * nearest power of 2 and used as the initial size of the queue.
   *
   * Returns: a new #GstAtomicQueue
   */
  GstAtomicQueue *
  gst_atomic_queue_new (guint initial_size)
  {
    GstAtomicQueue *queue;
  
    queue = g_new (GstAtomicQueue, 1);
  
    queue->refcount = 1;
  #ifdef LOW_MEM
    queue->num_readers = 0;
  #endif
    queue->head_mem = queue->tail_mem = new_queue_mem (initial_size, 0);
    queue->free_list = NULL;
  
    return queue;
  }
  
  /**
   * gst_atomic_queue_ref:
   * @queue: a #GstAtomicQueue
   *
   * Increase the refcount of @queue.
   */
  void
  gst_atomic_queue_ref (GstAtomicQueue * queue)
  {
    g_return_if_fail (queue != NULL);
  
    g_atomic_int_inc (&queue->refcount);
  }
  
  static void
  gst_atomic_queue_free (GstAtomicQueue * queue)
  {
    free_queue_mem (queue->head_mem);
    if (queue->head_mem != queue->tail_mem)
      free_queue_mem (queue->tail_mem);
    clear_free_list (queue);
    g_free (queue);
  }
  
  /**
   * gst_atomic_queue_unref:
   * @queue: a #GstAtomicQueue
   *
   * Unref @queue and free the memory when the refcount reaches 0.
   */
  void
  gst_atomic_queue_unref (GstAtomicQueue * queue)
  {
    g_return_if_fail (queue != NULL);
  
    if (g_atomic_int_dec_and_test (&queue->refcount))
      gst_atomic_queue_free (queue);
  }
  
  /**
   * gst_atomic_queue_peek:
   * @queue: a #GstAtomicQueue
   *
   * Peek the head element of the queue without removing it from the queue.
   *
   * Returns: (transfer none) (nullable): the head element of @queue or
   * %NULL when the queue is empty.
   */
  gpointer
  gst_atomic_queue_peek (GstAtomicQueue * queue)
  {
    GstAQueueMem *head_mem;
    gint head, tail, size;
  
    g_return_val_if_fail (queue != NULL, NULL);
  
    while (TRUE) {
      GstAQueueMem *next;
  
      head_mem = g_atomic_pointer_get (&queue->head_mem);
  
      head = g_atomic_int_get (&head_mem->head);
      tail = g_atomic_int_get (&head_mem->tail_read);
      size = head_mem->size;
  
      /* when we are not empty, we can continue */
      if (G_LIKELY (head != tail))
        break;
  
      /* else array empty, try to take next */
      next = g_atomic_pointer_get (&head_mem->next);
      if (next == NULL)
        return NULL;
  
      /* now we try to move the next array as the head memory. If we fail to do that,
       * some other reader managed to do it first and we retry */
      if (!g_atomic_pointer_compare_and_exchange (&queue->head_mem, head_mem,
              next))
        continue;
  
      /* when we managed to swing the head pointer the old head is now
       * useless and we add it to the freelist. We can't free the memory yet
       * because we first need to make sure no reader is accessing it anymore. */
      add_to_free_list (queue, head_mem);
    }
  
    return head_mem->array[head & size];
  }
  
  /**
   * gst_atomic_queue_pop:
   * @queue: a #GstAtomicQueue
   *
   * Get the head element of the queue.
   *
   * Returns: (transfer full): the head element of @queue or %NULL when
   * the queue is empty.
   */
  gpointer
  gst_atomic_queue_pop (GstAtomicQueue * queue)
  {
    gpointer ret;
    GstAQueueMem *head_mem;
    gint head, tail, size;
  
    g_return_val_if_fail (queue != NULL, NULL);
  
  #ifdef LOW_MEM
    g_atomic_int_inc (&queue->num_readers);
  #endif
  
    do {
      while (TRUE) {
        GstAQueueMem *next;
  
        head_mem = g_atomic_pointer_get (&queue->head_mem);
  
        head = g_atomic_int_get (&head_mem->head);
        tail = g_atomic_int_get (&head_mem->tail_read);
        size = head_mem->size;
  
        /* when we are not empty, we can continue */
        if G_LIKELY
          (head != tail)
              break;
  
        /* else array empty, try to take next */
        next = g_atomic_pointer_get (&head_mem->next);
        if (next == NULL)
          return NULL;
  
        /* now we try to move the next array as the head memory. If we fail to do that,
         * some other reader managed to do it first and we retry */
        if G_UNLIKELY
          (!g_atomic_pointer_compare_and_exchange (&queue->head_mem, head_mem,
                  next))
              continue;
  
        /* when we managed to swing the head pointer the old head is now
         * useless and we add it to the freelist. We can't free the memory yet
         * because we first need to make sure no reader is accessing it anymore. */
        add_to_free_list (queue, head_mem);
      }
  
      ret = head_mem->array[head & size];
    } while G_UNLIKELY
    (!g_atomic_int_compare_and_exchange (&head_mem->head, head, head + 1));
  
  #ifdef LOW_MEM
    /* decrement number of readers, when we reach 0 readers we can be sure that
     * none is accessing the memory in the free list and we can try to clean up */
    if (g_atomic_int_dec_and_test (&queue->num_readers))
      clear_free_list (queue);
  #endif
  
    return ret;
  }
  
  /**
   * gst_atomic_queue_push:
   * @queue: a #GstAtomicQueue
   * @data: the data
   *
   * Append @data to the tail of the queue.
   */
  void
  gst_atomic_queue_push (GstAtomicQueue * queue, gpointer data)
  {
    GstAQueueMem *tail_mem;
    gint head, tail, size;
  
    g_return_if_fail (queue != NULL);
  
    do {
      while (TRUE) {
        GstAQueueMem *mem;
  
        tail_mem = g_atomic_pointer_get (&queue->tail_mem);
        head = g_atomic_int_get (&tail_mem->head);
        tail = g_atomic_int_get (&tail_mem->tail_write);
        size = tail_mem->size;
  
        /* we're not full, continue */
        if G_LIKELY
          (tail - head <= size)
              break;
  
        /* else we need to grow the array, we store a mask so we have to add 1 */
        mem = new_queue_mem ((size << 1) + 1, tail);
  
        /* try to make our new array visible to other writers */
        if G_UNLIKELY
          (!g_atomic_pointer_compare_and_exchange (&queue->tail_mem, tail_mem,
                  mem)) {
          /* we tried to swap the new writer array but something changed. This is
           * because some other writer beat us to it, we free our memory and try
           * again */
          free_queue_mem (mem);
          continue;
          }
        /* make sure that readers can find our new array as well. The one who
         * manages to swap the pointer is the only one who can set the next
         * pointer to the new array */
        g_atomic_pointer_set (&tail_mem->next, mem);
      }
    } while G_UNLIKELY
    (!g_atomic_int_compare_and_exchange (&tail_mem->tail_write, tail, tail + 1));
  
    tail_mem->array[tail & size] = data;
  
    /* now wait until all writers have completed their write before we move the
     * tail_read to this new item. It is possible that other writers are still
     * updating the previous array slots and we don't want to reveal their changes
     * before they are done. FIXME, it would be nice if we didn't have to busy
     * wait here. */
    while G_UNLIKELY
      (!g_atomic_int_compare_and_exchange (&tail_mem->tail_read, tail, tail + 1));
  }
  
  /**
   * gst_atomic_queue_length:
   * @queue: a #GstAtomicQueue
   *
   * Get the amount of items in the queue.
   *
   * Returns: the number of elements in the queue.
   */
  guint
  gst_atomic_queue_length (GstAtomicQueue * queue)
  {
    GstAQueueMem *head_mem, *tail_mem;
    gint head, tail;
  
    g_return_val_if_fail (queue != NULL, 0);
  
  #ifdef LOW_MEM
    g_atomic_int_inc (&queue->num_readers);
  #endif
  
    head_mem = g_atomic_pointer_get (&queue->head_mem);
    head = g_atomic_int_get (&head_mem->head);
  
    tail_mem = g_atomic_pointer_get (&queue->tail_mem);
    tail = g_atomic_int_get (&tail_mem->tail_read);
  
  #ifdef LOW_MEM
    if (g_atomic_int_dec_and_test (&queue->num_readers))
      clear_free_list (queue);
  #endif
  
    return tail - head;
  }
  