GstDataQueue: GStreamer 1.0 Library Reference Manual

## GstDataQueue GstDataQueue — Threadsafe queueing object |

## Functions

gboolean | (*GstDataQueueCheckFullFunction) ()
void | (*GstDataQueueEmptyCallback) ()
void | (*GstDataQueueFullCallback) ()
GstDataQueue * | gst_data_queue_new ()
gboolean | gst_data_queue_push ()
gboolean | gst_data_queue_push_force ()
gboolean | gst_data_queue_pop ()
gboolean | gst_data_queue_peek ()
void | gst_data_queue_flush ()
void | gst_data_queue_set_flushing ()
gboolean | gst_data_queue_drop_head ()
gboolean | gst_data_queue_is_full ()
gboolean | gst_data_queue_is_empty ()
void | gst_data_queue_get_level ()
void | gst_data_queue_limits_changed ()

## Types and Values

struct | GstDataQueue
struct | GstDataQueueSize
struct | GstDataQueueItem

## Includes

    #include <gst/base/gstdataqueue.h>

## 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.

## Functions

### 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.

[skip]

#### Parameters

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.

### 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. If `fullcallback` or `emptycallback` are supplied, then the GstDataQueue will call the respective callback to signal full or empty condition. If the callbacks are NULL the GstDataQueue will instead emit 'full' and 'empty' signals.

[skip]

#### Parameters

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 passed to the `checkfull` , `fullcallback` , and `emptycallback` callbacks. |

#### Returns

a new GstDataQueue.

Since: 1.2

### 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.

[skip]

#### Parameters

queue | a GstDataQueue. |
item | a GstDataQueueItem. |

#### Returns

`TRUE` if the `item` was successfully pushed on the `queue` .

Since: 1.2

### 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.

[skip]

#### Parameters

queue | a GstDataQueue. |
item | a GstDataQueueItem. |

#### Returns

`TRUE` if the `item` was successfully pushed on the `queue` .

Since: 1.2

### 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.

[skip]

#### Parameters

queue | a GstDataQueue. |
item | pointer to store the returned GstDataQueueItem. |

#### Returns

`TRUE` if an `item` was successfully retrieved from the `queue` .

Since: 1.2

### gst_data_queue_peek ()

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

Retrieves the first `item` available on the `queue` without removing it. 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.

[skip]

#### Parameters

queue | a GstDataQueue. |
item | pointer to store the returned GstDataQueueItem. |

#### Returns

`TRUE` if an `item` was successfully retrieved from the `queue` .

Since: 1.2

### 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.

[skip]

#### Parameters

queue | a GstDataQueue. |

Since: 1.2

### 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.

[skip]

#### Parameters

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

Since: 1.2

### 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.

[skip]

#### Parameters

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

### 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.

[skip]

#### Parameters

queue | a GstDataQueue. |

#### Returns

`TRUE` if `queue` is full.

Since: 1.2

### gst_data_queue_is_empty ()

    gboolean
    gst_data_queue_is_empty (GstDataQueue *queue);

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

[skip]

#### Parameters

queue | a GstDataQueue. |

#### Returns

`TRUE` if `queue` is empty.

Since: 1.2

### gst_data_queue_get_level ()

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

Get the current level of the queue.

[skip]

#### Parameters

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

Since: 1.2

### 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 limits.

[skip]

#### Parameters

queue | The GstDataQueue |

Since: 1.2

## Types and Values

### struct GstDataQueue

    struct GstDataQueue {
      GObject object;
    };

Opaque GstDataQueue structure.

#### Members

GObject `object`; | the parent structure |

### struct GstDataQueueSize

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

Structure describing the size of a queue.

#### Members

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

### 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.

#### Members

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. |