## GstDataQueue GstDataQueue — Threadsafe queueing object |

## Synopsis

    #include <gst/base/gstdataqueue.h>

    struct              GstDataQueue;
    struct              GstDataQueueSize;
    gboolean            (*GstDataQueueCheckFullFunction)    (GstDataQueue *queue,
                                                             guint visible,
                                                             guint bytes,
                                                             guint64 time,
                                                             gpointer checkdata);
    struct              GstDataQueueItem;
    void                (*GstDataQueueEmptyCallback)        (GstDataQueue *queue,
                                                             gpointer checkdata);
    void                (*GstDataQueueFullCallback)         (GstDataQueue *queue,
                                                             gpointer checkdata);
    GstDataQueue *      gst_data_queue_new                  (GstDataQueueCheckFullFunction checkfull,
                                                             GstDataQueueFullCallback fullcallback,
                                                             GstDataQueueEmptyCallback emptycallback,
                                                             gpointer checkdata);
    gboolean            gst_data_queue_push                 (GstDataQueue *queue,
                                                             GstDataQueueItem *item);
    gboolean            gst_data_queue_push_force           (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);
    void                gst_data_queue_get_level            (GstDataQueue *queue,
                                                             GstDataQueueSize *level);
    void                gst_data_queue_limits_changed       (GstDataQueue *queue);

## Description

GstDataQueue is an object that handles threadsafe queueing of objects. It also provides size-related functionality. This object should be used for any GstElement that wishes to provide some sort of queueing functionality.

## Details

### struct GstDataQueue

    struct GstDataQueue {
      GObject object;
    };

Opaque GstDataQueue structure.

GObject `object`; | the parent structure

### struct GstDataQueueSize

    struct GstDataQueueSize {
      guint visible;
      guint bytes;
      guint64 time;
    };

Structure describing the size of a queue.

guint `visible`; | number of buffers
guint `bytes`; | number of bytes
guint64 `time`; | amount of time

### GstDataQueueCheckFullFunction ()

    gboolean            (*GstDataQueueCheckFullFunction)    (GstDataQueue *queue,
                                                             guint visible,
                                                             guint bytes,
                                                             guint64 time,
                                                             gpointer checkdata);

The prototype of the function used to inform the queue that it should be considered as full.

`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.
Returns : | TRUE if the queue should be considered full.

### struct GstDataQueueItem

    struct GstDataQueueItem {
      GstMiniObject *object;
      guint size;
      guint64 duration;
      gboolean visible;

      /* user supplied destroy function */
      GDestroyNotify destroy;
    };

Structure used by GstDataQueue. You can supply a different structure, as long as the top of the structure is identical to this structure.

GstMiniObject *`object`; | the GstMiniObject to queue.
guint `size`; | the size in bytes of the miniobject.
guint64 `duration`; | the duration in GstClockTime of the miniobject. Can not be GST_CLOCK_TIME_NONE.
gboolean `visible`; | TRUE if `object` should be considered as a visible object.
GDestroyNotify `destroy`; | The GDestroyNotify function to use to free the GstDataQueueItem. This function should also drop the reference to `object` the owner of the GstDataQueueItem is assumed to hold.

### GstDataQueueEmptyCallback ()

    void                (*GstDataQueueEmptyCallback)        (GstDataQueue *queue,
                                                             gpointer checkdata);

### GstDataQueueFullCallback ()

    void                (*GstDataQueueFullCallback)         (GstDataQueue *queue,
                                                             gpointer checkdata);

### gst_data_queue_new ()

    GstDataQueue *      gst_data_queue_new                  (GstDataQueueCheckFullFunction checkfull,
                                                             GstDataQueueFullCallback fullcallback,
                                                             GstDataQueueEmptyCallback emptycallback,
                                                             gpointer checkdata);

Creates a new GstDataQueue. The difference with `gst_data_queue_new` is that it will not emit the 'full' and 'empty' signals, but instead calling directly `fullcallback` or `emptycallback`.

`checkfull` : | the callback used to tell if the element considers the queue full or not.
`fullcallback` : | the callback which will be called when the queue is considered full.
`emptycallback` : | the callback which will be called when the queue is considered empty.
`checkdata` : | a gpointer that will be given in the `checkfull` callback.
Returns : | a new GstDataQueue.

Since 1.2.0

### gst_data_queue_push ()

    gboolean            gst_data_queue_push                 (GstDataQueue *queue,
                                                             GstDataQueueItem *item);

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.

Note that this function has slightly different semantics than `gst_pad_push()` and `gst_pad_push_event()`: this function only takes ownership of `item` and the GstMiniObject contained in `item` if the push was successful. If FALSE is returned, the caller is responsible for freeing `item` and its contents.

`queue` : | a GstDataQueue.
`item` : | a GstDataQueueItem.
Returns : | TRUE if the `item` was successfully pushed on the `queue`.

Since 1.2.0

### gst_data_queue_push_force ()

    gboolean            gst_data_queue_push_force           (GstDataQueue *queue,
                                                             GstDataQueueItem *item);

Pushes a GstDataQueueItem (or a structure that begins with the same fields) on the `queue`. It ignores if the `queue` is full or not and forces the `item` to be pushed anyway. MT safe.

Note that this function has slightly different semantics than `gst_pad_push()` and `gst_pad_push_event()`: this function only takes ownership of `item` and the GstMiniObject contained in `item` if the push was successful. If FALSE is returned, the caller is responsible for freeing `item` and its contents.

`queue` : | a GstDataQueue.
`item` : | a GstDataQueueItem.
Returns : | TRUE if the `item` was successfully pushed on the `queue`.

Since 1.2.0

### gst_data_queue_pop ()

    gboolean            gst_data_queue_pop                  (GstDataQueue *queue,
                                                             GstDataQueueItem **item);

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.

`queue` : | a GstDataQueue.
`item` : | pointer to store the returned GstDataQueueItem.
Returns : | TRUE if an `item` was successfully retrieved from the `queue`.

Since 1.2.0

### gst_data_queue_flush ()

    void                gst_data_queue_flush                (GstDataQueue *queue);

Flushes all the contents of the `queue`. Any call to gst_data_queue_push and gst_data_queue_pop will be released. MT safe.

`queue` : | a GstDataQueue.

Since 1.2.0

### gst_data_queue_set_flushing ()

    void                gst_data_queue_set_flushing         (GstDataQueue *queue,
                                                             gboolean flushing);

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.

`queue` : | a GstDataQueue.
`flushing` : | a gboolean stating if the queue will be flushing or not.

Since 1.2.0

### gst_data_queue_drop_head ()

    gboolean            gst_data_queue_drop_head            (GstDataQueue *queue,
                                                             GType type);

Pop and unref the head-most GstMiniObject with the given GType.

`queue` : | The GstDataQueue to drop an item from.
`type` : | The GType of the item to drop.
Returns : | TRUE if an element was removed.

Since 1.2.0

### gst_data_queue_is_full ()

    gboolean            gst_data_queue_is_full              (GstDataQueue *queue);

Queries if `queue` is full. This check will be done using the GstDataQueueCheckFullFunction registered with `queue`. MT safe.

`queue` : | a GstDataQueue.
Returns : | TRUE if `queue` is full.

Since 1.2.0

### gst_data_queue_is_empty ()

    gboolean            gst_data_queue_is_empty             (GstDataQueue *queue);

Queries if there are any items in the `queue`. MT safe.

`queue` : | a GstDataQueue.
Returns : | TRUE if `queue` is empty.

Since 1.2.0

### gst_data_queue_get_level ()

    void                gst_data_queue_get_level            (GstDataQueue *queue,
                                                             GstDataQueueSize *level);

Get the current level of the queue.

`queue` : | The GstDataQueue
`level` : | the location to store the result

Since 1.2.0

### gst_data_queue_limits_changed ()

    void                gst_data_queue_limits_changed       (GstDataQueue *queue);

Inform the queue that the limits for the fullness check have changed and that any blocking `gst_data_queue_push()` should be unblocked to recheck the limts.

`queue` : | The GstDataQueue

Since 1.2.0