GstDataQueue

GstDataQueue — Threadsafe queueing object

Functions

Types and Values

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.