libs/gst/base/: New GstDataQueue object for threadsafe queueing. Most useful for elements that need some queueing fun...

Original commit message from CVS:
* libs/gst/base/Makefile.am:
* libs/gst/base/gstdataqueue.c: (gst_data_queue_get_type),
(gst_data_queue_base_init), (gst_data_queue_class_init),
(gst_data_queue_init), (gst_data_queue_new),
(gst_data_queue_cleanup), (gst_data_queue_finalize),
(gst_data_queue_locked_flush), (gst_data_queue_locked_is_empty),
(gst_data_queue_locked_is_full), (gst_data_queue_flush),
(gst_data_queue_is_empty), (gst_data_queue_is_full),
(gst_data_queue_set_flushing), (gst_data_queue_push),
(gst_data_queue_pop), (gst_data_queue_drop_head),
(gst_data_queue_set_property), (gst_data_queue_get_property):
* libs/gst/base/gstdataqueue.h:
New GstDataQueue object for threadsafe queueing. Most useful for
elements that need some queueing functionnality.
* docs/libs/gstreamer-libs-docs.sgml:
* docs/libs/gstreamer-libs-sections.txt:
Insert documentation for GstDataQueue
* plugins/elements/Makefile.am:
* plugins/elements/gstelements.c:
* plugins/elements/gstmultiqueue.c: (gst_multi_queue_base_init),
(gst_multi_queue_class_init), (gst_multi_queue_init),
(gst_multi_queue_finalize), (gst_multi_queue_set_property),
(gst_multi_queue_get_property), (gst_multi_queue_request_new_pad),
(gst_multi_queue_release_pad), (gst_single_queue_push_one),
(gst_multi_queue_item_destroy), (gst_multi_queue_item_new),
(gst_multi_queue_loop), (gst_multi_queue_chain),
(gst_multi_queue_sink_activate_push), (gst_multi_queue_sink_event),
(gst_multi_queue_getcaps), (gst_multi_queue_bufferalloc),
(gst_multi_queue_src_activate_push), (gst_multi_queue_acceptcaps),
(gst_multi_queue_src_event), (gst_multi_queue_src_query),
(wake_up_next_non_linked), (compute_next_non_linked),
(single_queue_overrun_cb), (single_queue_underrun_cb),
(single_queue_check_full), (gst_single_queue_new):
* plugins/elements/gstmultiqueue.h:
New multiqueue element, using GstDataQueue. Used for queuing multiple
streams.
Closes #344639 and #347785

3 files changed, 746 insertions, 2 deletions

diff --git a/libs/gst/base/Makefile.am b/libs/gst/base/Makefile.am
index ab5b99097..0c72e5da3 100644
--- a/libs/gst/base/Makefile.am
+++ b/libs/gst/base/Makefile.am
@@ -9,7 +9,8 @@ libgstbase_@GST_MAJORMINOR@_la_SOURCES = \
 	gstbasetransform.c	\
 	gstcollectpads.c	\
 	gstpushsrc.c		\
-	gsttypefindhelper.c
+	gsttypefindhelper.c	\
+	gstdataqueue.c
 
 libgstbase_@GST_MAJORMINOR@_la_CFLAGS = $(GST_OBJ_CFLAGS)
 libgstbase_@GST_MAJORMINOR@_la_LIBADD = $(GST_OBJ_LIBS)
@@ -25,7 +26,8 @@ libgstbase_@GST_MAJORMINOR@include_HEADERS =	\
 	gstbasetransform.h	\
 	gstcollectpads.h	\
 	gstpushsrc.h		\
-	gsttypefindhelper.h	
+	gsttypefindhelper.h	\
+	gstdataqueue.h
 
 CLEANFILES = *.gcno *.gcda *.gcov
 
diff --git a/libs/gst/base/gstdataqueue.c b/libs/gst/base/gstdataqueue.c
new file mode 100644
index 000000000..a9683ec05
--- /dev/null
+++ b/libs/gst/base/gstdataqueue.c
@@ -0,0 +1,589 @@
+/* GStreamer
+ * Copyright (C) 2006 Edward Hervey <edward@fluendo.com>
+ *
+ * gstdataqueue.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., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+/**
+ * SECTION:gstdataqueue
+ * @short_description: Threadsafe queueing object
+ *
+ * #GstDataQueue is an object that handles threadsafe queueing of object. It
+ * also provides size-related functionnality. This object should be used for
+ * any #GstElement that wishes to provide some sort of queueing functionnality.
+ */
+
+#include <gst/gst.h>
+#include "gstdataqueue.h"
+
+GST_DEBUG_CATEGORY_STATIC (data_queue_debug);
+#define GST_CAT_DEFAULT (data_queue_debug)
+GST_DEBUG_CATEGORY_STATIC (data_queue_dataflow);
+
+
+/* Queue signals and args */
+enum
+{
+  SIGNAL_EMPTY,
+  SIGNAL_FULL,
+  LAST_SIGNAL
+};
+
+enum
+{
+  ARG_0,
+  ARG_CUR_LEVEL_VISIBLE,
+  ARG_CUR_LEVEL_BYTES,
+  ARG_CUR_LEVEL_TIME,
+  /* FILL ME */
+};
+
+#define GST_DATA_QUEUE_MUTEX_LOCK(q) G_STMT_START {                     \
+    GST_CAT_LOG (data_queue_dataflow,					\
+      "locking qlock from thread %p",                                   \
+      g_thread_self ());                                                \
+  g_mutex_lock (q->qlock);                                              \
+  GST_CAT_LOG (data_queue_dataflow,					\
+      "locked qlock from thread %p",                                    \
+      g_thread_self ());                                                \
+} G_STMT_END
+
+#define GST_DATA_QUEUE_MUTEX_LOCK_CHECK(q, label) G_STMT_START {	\
+    GST_DATA_QUEUE_MUTEX_LOCK (q);					\
+    if (q->flushing)							\
+      goto label;							\
+  } G_STMT_END
+
+#define GST_DATA_QUEUE_MUTEX_UNLOCK(q) G_STMT_START {                   \
+    GST_CAT_LOG (data_queue_dataflow,					\
+      "unlocking qlock from thread %p",                                 \
+      g_thread_self ());                                                \
+  g_mutex_unlock (q->qlock);                                            \
+} G_STMT_END
+
+#define STATUS(q, msg)							\
+  GST_CAT_LOG (data_queue_dataflow,					\
+	       "queue:%p " msg ": %u visible items, %u "	\
+	       "bytes, %"G_GUINT64_FORMAT	\
+	       " ns, %u elements",					\
+	       queue,							\
+	       q->cur_level.visible,					\
+	       q->cur_level.bytes,					\
+	       q->cur_level.time,					\
+	       q->queue->length)
+
+static void gst_data_queue_base_init (GstDataQueueClass * klass);
+static void gst_data_queue_class_init (GstDataQueueClass * klass);
+static void gst_data_queue_init (GstDataQueue * queue);
+static void gst_data_queue_finalize (GObject * object);
+
+static void gst_data_queue_set_property (GObject * object,
+    guint prop_id, const GValue * value, GParamSpec * pspec);
+static void gst_data_queue_get_property (GObject * object,
+    guint prop_id, GValue * value, GParamSpec * pspec);
+
+static GObjectClass *parent_class = NULL;
+static guint gst_data_queue_signals[LAST_SIGNAL] = { 0 };
+
+GType
+gst_data_queue_get_type (void)
+{
+  static GType queue_type = 0;
+
+  if (!queue_type) {
+    static const GTypeInfo queue_info = {
+      sizeof (GstDataQueueClass),
+      (GBaseInitFunc) gst_data_queue_base_init,
+      NULL,
+      (GClassInitFunc) gst_data_queue_class_init,
+      NULL,
+      NULL,
+      sizeof (GstDataQueue),
+      0,
+      (GInstanceInitFunc) gst_data_queue_init,
+      NULL
+    };
+
+    queue_type = g_type_register_static (G_TYPE_OBJECT,
+        "GstDataQueue", &queue_info, 0);
+    GST_DEBUG_CATEGORY_INIT (data_queue_debug, "dataqueue", 0,
+        "data queue object");
+    GST_DEBUG_CATEGORY_INIT (data_queue_dataflow, "data_queue_dataflow", 0,
+        "dataflow inside the data queue object");
+  }
+
+  return queue_type;
+}
+
+static void
+gst_data_queue_base_init (GstDataQueueClass * klass)
+{
+  /* Do we need anything here ?? */
+  return;
+}
+
+static void
+gst_data_queue_class_init (GstDataQueueClass * klass)
+{
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+
+  parent_class = g_type_class_peek_parent (klass);
+
+  gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_data_queue_set_property);
+  gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_data_queue_get_property);
+
+  /* signals */
+  /**
+   * GstDataQueue::empty:
+   * @queue: the queue instance
+   *
+   * Reports that the queue became empty (empty).
+   * A queue is empty if the total amount of visible items inside it (num-visible, time,
+   * size) is lower than the boundary values which can be set through the GObject
+   * properties.
+   */
+  gst_data_queue_signals[SIGNAL_EMPTY] =
+      g_signal_new ("empty", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
+      G_STRUCT_OFFSET (GstDataQueueClass, empty), NULL, NULL,
+      g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+
+  /**
+   * GstDataQueue::full:
+   * @queue: the queue instance
+   *
+   * Reports that the queue became full (full).
+   * A queue is full if the total amount of data inside it (num-visible, time,
+   * size) is higher than the boundary values which can be set through the GObject
+   * properties.
+   */
+  gst_data_queue_signals[SIGNAL_FULL] =
+      g_signal_new ("full", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
+      G_STRUCT_OFFSET (GstDataQueueClass, full), NULL, NULL,
+      g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
+
+  /* properties */
+  g_object_class_install_property (gobject_class, ARG_CUR_LEVEL_BYTES,
+      g_param_spec_uint ("current-level-bytes", "Current level (kB)",
+          "Current amount of data in the queue (bytes)",
+          0, G_MAXUINT, 0, G_PARAM_READABLE));
+  g_object_class_install_property (gobject_class, ARG_CUR_LEVEL_VISIBLE,
+      g_param_spec_uint ("current-level-visible",
+          "Current level (visible items)",
+          "Current number of visible items in the queue", 0, G_MAXUINT, 0,
+          G_PARAM_READABLE));
+  g_object_class_install_property (gobject_class, ARG_CUR_LEVEL_TIME,
+      g_param_spec_uint64 ("current-level-time", "Current level (ns)",
+          "Current amount of data in the queue (in ns)", 0, G_MAXUINT64, 0,
+          G_PARAM_READABLE));
+
+  /* set several parent class virtual functions */
+  gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_data_queue_finalize);
+
+}
+
+static void
+gst_data_queue_init (GstDataQueue * queue)
+{
+  queue->cur_level.visible = 0; /* no content */
+  queue->cur_level.bytes = 0;   /* no content */
+  queue->cur_level.time = 0;    /* no content */
+
+  queue->checkfull = NULL;
+
+  queue->qlock = g_mutex_new ();
+  queue->item_add = g_cond_new ();
+  queue->item_del = g_cond_new ();
+  queue->queue = g_queue_new ();
+
+  GST_DEBUG ("initialized queue's not_empty & not_full conditions");
+}
+
+/**
+ * gst_data_queue_new:
+ * @checkfull: the callback used to tell if the element considers the queue full
+ * or not.
+ * @checkdata: a #gpointer that will be given in the @checkfull callback.
+ *
+ * Returns: a new #GstDataQueue.
+ */
+
+GstDataQueue *
+gst_data_queue_new (GstDataQueueCheckFullFunction checkfull, gpointer checkdata)
+{
+  GstDataQueue *ret;
+
+  g_return_val_if_fail (checkfull != NULL, NULL);
+
+  ret = g_object_new (GST_TYPE_DATA_QUEUE, NULL);
+  ret->checkfull = checkfull;
+  ret->checkdata = checkdata;
+
+  return ret;
+}
+
+static void
+gst_data_queue_cleanup (GstDataQueue * queue)
+{
+  while (!g_queue_is_empty (queue->queue)) {
+    GstDataQueueItem *item = g_queue_pop_head (queue->queue);
+
+    /* Just call the destroy notify on the item */
+    item->destroy (item);
+  }
+  queue->cur_level.visible = 0;
+  queue->cur_level.bytes = 0;
+  queue->cur_level.time = 0;
+
+}
+
+/* called only once, as opposed to dispose */
+static void
+gst_data_queue_finalize (GObject * object)
+{
+  GstDataQueue *queue = GST_DATA_QUEUE (object);
+
+  GST_DEBUG ("finalizing queue");
+
+  gst_data_queue_cleanup (queue);
+  g_queue_free (queue->queue);
+
+  GST_DEBUG ("free mutex");
+  g_mutex_free (queue->qlock);
+  GST_DEBUG ("done free mutex");
+
+  g_cond_free (queue->item_add);
+  g_cond_free (queue->item_del);
+
+  if (G_OBJECT_CLASS (parent_class)->finalize)
+    G_OBJECT_CLASS (parent_class)->finalize (object);
+}
+
+static void
+gst_data_queue_locked_flush (GstDataQueue * queue)
+{
+  STATUS (queue, "before flushing");
+  gst_data_queue_cleanup (queue);
+  STATUS (queue, "after flushing");
+  /* we deleted something... */
+  g_cond_signal (queue->item_del);
+}
+
+static gboolean
+gst_data_queue_locked_is_empty (GstDataQueue * queue)
+{
+  return (queue->queue->length == 0);
+}
+
+static gboolean
+gst_data_queue_locked_is_full (GstDataQueue * queue)
+{
+  return queue->checkfull (queue, queue->cur_level.visible,
+      queue->cur_level.bytes, queue->cur_level.time, queue->checkdata);
+}
+
+/**
+ * gst_data_queue_flush:
+ * @queue: a #GstDataQueue.
+ *
+ * Flushes all the contents of the @queue. Any call to #gst_data_queue_pull and
+ * #gst_data_queue_pop will be released.
+ * MT safe.
+ */
+
+void
+gst_data_queue_flush (GstDataQueue * queue)
+{
+  GST_DEBUG ("queue:%p", queue);
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+  gst_data_queue_locked_flush (queue);
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+}
+
+/**
+ * gst_data_queue_is_empty:
+ * @queue: a #GstDataQueue.
+ *
+ * Queries if there are any items in the @queue.
+ * MT safe.
+ *
+ * Returns: #TRUE if @queue is empty.
+ */
+
+gboolean
+gst_data_queue_is_empty (GstDataQueue * queue)
+{
+  gboolean res;
+
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+  res = gst_data_queue_locked_is_empty (queue);
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+
+  return res;
+}
+
+/**
+ * gst_data_queue_is_full:
+ * @queue: a #GstDataQueue.
+ *
+ * Queries if @queue is full. This check will be done using the
+ * #GstDataQueueCheckFullCallback registered with @queue.
+ * MT safe.
+ *
+ * Returns: #TRUE if @queue is full.
+ */
+
+gboolean
+gst_data_queue_is_full (GstDataQueue * queue)
+{
+  gboolean res;
+
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+  res = gst_data_queue_locked_is_full (queue);
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+
+  return res;
+}
+
+/**
+ * gst_data_queue_set_flushing:
+ * @queue: a #GstDataQueue.
+ * @flushing: a #gboolean stating if the queue will be flushing or not.
+ *
+ * Sets the queue to flushing state if @flushing is #TRUE. If set to flushing
+ * state, any incoming data on the @queue will be discarded. Any call currently
+ * blocking on #gst_data_queue_push or #gst_data_queue_pop will return straight
+ * away with a return value of #FALSE. While the @queue is in flushing state, 
+ * all calls to those two functions will return #FALSE.
+ * MT Safe.
+ */
+
+void
+gst_data_queue_set_flushing (GstDataQueue * queue, gboolean flushing)
+{
+
+  GST_DEBUG ("queue:%p , flushing:%d", queue, flushing);
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+  queue->flushing = flushing;
+  if (flushing) {
+    /* release push/pop functions */
+    g_cond_signal (queue->item_add);
+    g_cond_signal (queue->item_del);
+  }
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+}
+
+/**
+ * gst_data_queue_push:
+ * @queue: a #GstDataQueue.
+ * @item: a #GstDataQueueItem.
+ *
+ * Pushes a #GstDataQueueItem (or a structure that begins with the same fields)
+ * on the @queue. If the @queue is full, the call will block until space is
+ * available, OR the @queue is set to flushing state.
+ * MT safe.
+ *
+ * Returns: #TRUE if the @item was successfully pushed on the @queue.
+ */
+gboolean
+gst_data_queue_push (GstDataQueue * queue, GstDataQueueItem * item)
+{
+  gboolean res = FALSE;
+
+  GST_DATA_QUEUE_MUTEX_LOCK_CHECK (queue, done);
+
+  STATUS (queue, "before pushing");
+
+  /* We ALWAYS need to check for queue fillness */
+  while (gst_data_queue_locked_is_full (queue)) {
+    GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+    g_signal_emit (G_OBJECT (queue), gst_data_queue_signals[SIGNAL_FULL], 0);
+    GST_DATA_QUEUE_MUTEX_LOCK_CHECK (queue, done);
+
+    /* signal might have removed some items */
+    while (gst_data_queue_locked_is_full (queue)) {
+      g_cond_wait (queue->item_del, queue->qlock);
+      if (queue->flushing)
+        goto done;
+    }
+  }
+
+  g_queue_push_tail (queue->queue, item);
+  res = TRUE;
+
+  if (item->visible)
+    queue->cur_level.visible++;
+  queue->cur_level.bytes += item->size;
+  queue->cur_level.time += item->duration;
+
+  STATUS (queue, "after pushing");
+
+  g_cond_signal (queue->item_add);
+
+done:
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+
+  GST_DEBUG ("queue:%p, result:%d", queue, res);
+
+  return res;
+}
+
+/**
+ * gst_data_queue_pop:
+ * @queue: a #GstDataQueue.
+ * @item: pointer to store the returned #GstDataQueueItem.
+ *
+ * Retrieves the first @item available on the @queue. If the queue is currently
+ * empty, the call will block until at least one item is available, OR the
+ * @queue is set to the flushing state.
+ * MT safe.
+ *
+ * Returns: #TRUE if an @item was successfully retrieved from the @queue.
+ */
+
+gboolean
+gst_data_queue_pop (GstDataQueue * queue, GstDataQueueItem ** item)
+{
+  gboolean res = FALSE;
+
+  GST_DEBUG ("queue:%p", queue);
+
+  g_return_val_if_fail (item != NULL, FALSE);
+
+  GST_DATA_QUEUE_MUTEX_LOCK_CHECK (queue, done);
+
+  STATUS (queue, "before popping");
+
+  while (gst_data_queue_locked_is_empty (queue)) {
+    GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+    g_signal_emit (G_OBJECT (queue), gst_data_queue_signals[SIGNAL_EMPTY], 0);
+    GST_DATA_QUEUE_MUTEX_LOCK_CHECK (queue, done);
+
+    while (gst_data_queue_locked_is_empty (queue)) {
+      g_cond_wait (queue->item_add, queue->qlock);
+      if (queue->flushing)
+        goto done;
+    }
+  }
+
+  /* Get the item from the GQueue */
+  *item = g_queue_pop_head (queue->queue);
+  res = TRUE;
+
+  /* update current level counter */
+  if ((*item)->visible)
+    queue->cur_level.visible--;
+  queue->cur_level.bytes -= (*item)->size;
+  queue->cur_level.time -= (*item)->duration;
+
+  g_cond_signal (queue->item_del);
+
+done:
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+
+  GST_DEBUG ("queue:%p , res:%d", queue, res);
+
+  return res;
+}
+
+/**
+ * gst_data_queue_drop_head:
+ * @queue: The #GstDataQueue to drop an item from.
+ * @type: The #GType of the item to drop.
+ *
+ * Pop and unref the head-most #GstMiniObject with the given #GType.
+ *
+ * Returns: TRUE if an element was removed.
+ */
+
+gboolean
+gst_data_queue_drop_head (GstDataQueue * queue, GType type)
+{
+  gboolean res = FALSE;
+  GList *item;
+  GstDataQueueItem *leak = NULL;
+
+  GST_DEBUG ("queue:%p", queue);
+
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+  for (item = g_queue_peek_head_link (queue->queue); item; item = item->next) {
+    GstDataQueueItem *tmp = (GstDataQueueItem *) item->data;
+
+    if (G_TYPE_CHECK_INSTANCE_TYPE (tmp->object, type)) {
+      leak = tmp;
+      break;
+    }
+  }
+
+  if (!leak)
+    goto done;
+
+  g_queue_delete_link (queue->queue, item);
+
+  if (leak->visible)
+    queue->cur_level.visible--;
+  queue->cur_level.bytes -= leak->size;
+  queue->cur_level.time -= leak->duration;
+
+  leak->destroy (leak);
+
+  res = TRUE;
+
+done:
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+
+  GST_DEBUG ("queue:%p , res:%d", queue, res);
+
+  return res;
+}
+
+static void
+gst_data_queue_set_property (GObject * object,
+    guint prop_id, const GValue * value, GParamSpec * pspec)
+{
+  switch (prop_id) {
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+      break;
+  }
+}
+
+static void
+gst_data_queue_get_property (GObject * object,
+    guint prop_id, GValue * value, GParamSpec * pspec)
+{
+  GstDataQueue *queue = GST_DATA_QUEUE (object);
+
+  GST_DATA_QUEUE_MUTEX_LOCK (queue);
+
+  switch (prop_id) {
+    case ARG_CUR_LEVEL_BYTES:
+      g_value_set_uint (value, queue->cur_level.bytes);
+      break;
+    case ARG_CUR_LEVEL_VISIBLE:
+      g_value_set_uint (value, queue->cur_level.visible);
+      break;
+    case ARG_CUR_LEVEL_TIME:
+      g_value_set_uint64 (value, queue->cur_level.time);
+      break;
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+      break;
+  }
+
+  GST_DATA_QUEUE_MUTEX_UNLOCK (queue);
+}
diff --git a/libs/gst/base/gstdataqueue.h b/libs/gst/base/gstdataqueue.h
new file mode 100644
index 000000000..b3cd87b55
--- /dev/null
+++ b/libs/gst/base/gstdataqueue.h
@@ -0,0 +1,153 @@
+/* GStreamer
+ * Copyright (C) 2006 Edward Hervey <edward@fluendo.com>
+ *
+ * gstdataqueue.h:
+ *
+ * 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., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+
+#ifndef __GST_DATA_QUEUE_H__
+#define __GST_DATA_QUEUE_H__
+
+#include <gst/gst.h>
+
+G_BEGIN_DECLS
+#define GST_TYPE_DATA_QUEUE \
+  (gst_data_queue_get_type())
+#define GST_DATA_QUEUE(obj) \
+  (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DATA_QUEUE,GstDataQueue))
+#define GST_DATA_QUEUE_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_DATA_QUEUE,GstDataQueueClass))
+#define GST_IS_DATA_QUEUE(obj) \
+  (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DATA_QUEUE))
+#define GST_IS_DATA_QUEUE_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_DATA_QUEUE))
+typedef struct _GstDataQueue GstDataQueue;
+typedef struct _GstDataQueueClass GstDataQueueClass;
+typedef struct _GstDataQueueSize GstDataQueueSize;
+typedef struct _GstDataQueueItem GstDataQueueItem;
+
+/**
+ * GstDataQueueItem:
+ * @object: the #GstMiniObject to queue.
+ * @size: the size in bytes of the miniobject.
+ * @duration: the duration in #GstClockTime of the miniobject. Can not be
+ * #GST_CLOCK_TIME_NONE.
+ * @visible: #TRUE if @object should be considered as a visible object.
+ * @destroy: The #GDestroyNotify to use to free the #GstDataQueueItem.
+ *
+ * Structure used by #GstDataQueue. You can supply a different structure, as
+ * long as the top of the structure is identical to this structure.
+ */
+
+struct _GstDataQueueItem
+{
+  GstMiniObject *object;
+  guint size;
+  guint64 duration;
+  gboolean visible;
+
+  /* user supplied destroy function */
+  GDestroyNotify destroy;
+};
+
+/**
+ * GstDataQueueSize:
+ * @visible: number of buffers
+ * @bytes: number of bytes
+ * @time: amount of time
+ *
+ * Structure describing the size of a queue.
+ */
+struct _GstDataQueueSize
+{
+  guint visible;
+  guint bytes;
+  guint64 time;
+};
+
+/**
+ * GstDataQueueCheckFullFunction:
+ * @queue: a #GstDataQueue.
+ * @visible: The number of visible items currently in the queue.
+ * @bytes: The amount of bytes currently in the queue.
+ * @time: The accumulated duration of the items currently in the queue.
+ * @checkdata: The #gpointer registered when the #GstDataQueue was created.
+ * 
+ * The prototype of the function used to inform the queue that it should be
+ * considered as full.
+ *
+ * Returns: #TRUE if the queue should be considered full.
+ */
+typedef gboolean (*GstDataQueueCheckFullFunction) (GstDataQueue * queue,
+    guint visible, guint bytes, guint64 time, gpointer checkdata);
+
+/**
+ * GstDataQueue:
+ *
+ * Opaque #GstDataQueue structure.
+ */
+struct _GstDataQueue
+{
+  GObject object;
+
+  /*< private > */
+  /* the queue of data we're keeping our grubby hands on */
+  GQueue *queue;
+
+  GstDataQueueSize cur_level;   /* size of the queue */
+  GstDataQueueCheckFullFunction checkfull;      /* Callback to check if the queue is full */
+  gpointer *checkdata;
+
+  GMutex *qlock;                /* lock for queue (vs object lock) */
+  GCond *item_add;              /* signals buffers now available for reading */
+  GCond *item_del;              /* signals space now available for writing */
+  gboolean flushing;            /* indicates whether conditions where signalled because
+                                 * of external flushing */
+
+  gpointer _gst_reserved[GST_PADDING];
+};
+
+struct _GstDataQueueClass
+{
+  GObjectClass parent_class;
+
+  /* signals */
+  void (*empty) (GstDataQueue * queue);
+  void (*full) (GstDataQueue * queue);
+
+  gpointer _gst_reserved[GST_PADDING];
+};
+
+GType gst_data_queue_get_type (void);
+
+GstDataQueue *gst_data_queue_new (GstDataQueueCheckFullFunction checkfull,
+    gpointer checkdata);
+
+gboolean gst_data_queue_push (GstDataQueue * queue, GstDataQueueItem * item);
+gboolean gst_data_queue_pop (GstDataQueue * queue, GstDataQueueItem ** item);
+
+void gst_data_queue_flush (GstDataQueue * queue);
+void gst_data_queue_set_flushing (GstDataQueue * queue, gboolean flushing);
+
+gboolean gst_data_queue_drop_head (GstDataQueue * queue, GType type);
+
+gboolean gst_data_queue_is_full (GstDataQueue * queue);
+gboolean gst_data_queue_is_empty (GstDataQueue * queue);
+
+G_END_DECLS
+#endif /* __GST_DATA_QUEUE_H__ */