1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>multiqueue</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
7 <link rel="home" href="index.html" title="GStreamer Core Plugins 0.10 Plugins Reference Manual">
8 <link rel="up" href="ch01.html" title="gstreamer Elements">
9 <link rel="prev" href="gstreamer-plugins-input-selector.html" title="input-selector">
10 <link rel="next" href="gstreamer-plugins-output-selector.html" title="output-selector">
11 <meta name="generator" content="GTK-Doc V1.17 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
17 <td><a accesskey="p" href="gstreamer-plugins-input-selector.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">GStreamer Core Plugins 0.10 Plugins Reference Manual</th>
21 <td><a accesskey="n" href="gstreamer-plugins-output-selector.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#gstreamer-plugins-multiqueue.synopsis" class="shortcut">Top</a>
26 <a href="#gstreamer-plugins-multiqueue.description" class="shortcut">Description</a>
28 <a href="#gstreamer-plugins-multiqueue.object-hierarchy" class="shortcut">Object Hierarchy</a>
30 <a href="#gstreamer-plugins-multiqueue.properties" class="shortcut">Properties</a>
32 <a href="#gstreamer-plugins-multiqueue.signals" class="shortcut">Signals</a>
35 <div class="refentry">
36 <a name="gstreamer-plugins-multiqueue"></a><div class="titlepage"></div>
37 <div class="refnamediv"><table width="100%"><tr>
39 <h2><span class="refentrytitle"><a name="gstreamer-plugins-multiqueue.top_of_page"></a>multiqueue</span></h2>
40 <p>multiqueue — Multiple data queue</p>
42 <td valign="top" align="right"></td>
44 <div class="refsynopsisdiv">
45 <a name="gstreamer-plugins-multiqueue.synopsis"></a><h2>Synopsis</h2>
46 <a name="GstMultiQueue"></a><pre class="synopsis">struct <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-struct" title="struct GstMultiQueue">GstMultiQueue</a>;
49 <div class="refsect1">
50 <a name="gstreamer-plugins-multiqueue.object-hierarchy"></a><h2>Object Hierarchy</h2>
51 <pre class="synopsis">
52 <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
53 +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstObject.html">GstObject</a>
54 +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstElement.html">GstElement</a>
58 <div class="refsect1">
59 <a name="gstreamer-plugins-multiqueue.properties"></a><h2>Properties</h2>
60 <pre class="synopsis">
61 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-buffers" title='The "extra-size-buffers" property'>extra-size-buffers</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write
62 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-bytes" title='The "extra-size-bytes" property'>extra-size-bytes</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write
63 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-time" title='The "extra-size-time" property'>extra-size-time</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a> : Read / Write
64 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-buffers" title='The "max-size-buffers" property'>max-size-buffers</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write
65 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-bytes" title='The "max-size-bytes" property'>max-size-bytes</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write
66 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-time" title='The "max-size-time" property'>max-size-time</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a> : Read / Write
67 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--high-percent" title='The "high-percent" property'>high-percent</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write
68 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--low-percent" title='The "low-percent" property'>low-percent</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write
69 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--use-buffering" title='The "use-buffering" property'>use-buffering</a>" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> : Read / Write
72 <div class="refsect1">
73 <a name="gstreamer-plugins-multiqueue.signals"></a><h2>Signals</h2>
74 <pre class="synopsis">
75 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-overrun" title='The "overrun" signal'>overrun</a>" : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a>
76 "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-underrun" title='The "underrun" signal'>underrun</a>" : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a>
79 <div class="refsect1">
80 <a name="gstreamer-plugins-multiqueue.description"></a><h2>Description</h2>
83 <div class="refsect2">
84 <a name="idp10428752"></a><p>
85 Multiqueue is similar to a normal <a class="link" href="gstreamer-plugins-queue.html#GstQueue"><span class="type">GstQueue</span></a> with the following additional
88 <div class="orderedlist"><ol class="orderedlist" type="1">
89 <li class="listitem"><div class="itemizedlist">
90 <p class="title"><b>Multiple streamhandling</b></p>
91 <ul class="itemizedlist" type="disc"><li class="listitem">
93 The element handles queueing data on more than one stream at once. To
94 achieve such a feature it has request sink pads (sink%d) and
95 'sometimes' src pads (src%d).
98 When requesting a given sinkpad with <a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstElement.html#gst-element-get-request-pad"><code class="function">gst_element_get_request_pad()</code></a>,
99 the associated srcpad for that stream will be created.
100 Example: requesting sink1 will generate src1.
104 <li class="listitem"><div class="itemizedlist">
105 <p class="title"><b>Non-starvation on multiple streams</b></p>
106 <ul class="itemizedlist" type="disc"><li class="listitem">
108 If more than one stream is used with the element, the streams' queues
109 will be dynamically grown (up to a limit), in order to ensure that no
110 stream is risking data starvation. This guarantees that at any given
111 time there are at least N bytes queued and available for each individual
115 If an EOS event comes through a srcpad, the associated queue will be
116 considered as 'not-empty' in the queue-size-growing algorithm.
120 <li class="listitem"><div class="itemizedlist">
121 <p class="title"><b>Non-linked srcpads graceful handling</b></p>
122 <ul class="itemizedlist" type="disc"><li class="listitem">
124 In order to better support dynamic switching between streams, the multiqueue
125 (unlike the current GStreamer queue) continues to push buffers on non-linked
126 pads rather than shutting down.
129 In addition, to prevent a non-linked stream from very quickly consuming all
130 available buffers and thus 'racing ahead' of the other streams, the element
131 must ensure that buffers and inlined events for a non-linked stream are pushed
132 in the same order as they were received, relative to the other streams
133 controlled by the element. This means that a buffer cannot be pushed to a
134 non-linked pad any sooner than buffers in any other stream which were received
143 Data is queued until one of the limits specified by the
144 <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-buffers" title='The "max-size-buffers" property'><span class="type">"max-size-buffers"</span></a>, <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-bytes" title='The "max-size-bytes" property'><span class="type">"max-size-bytes"</span></a> and/or
145 <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-time" title='The "max-size-time" property'><span class="type">"max-size-time"</span></a> properties has been reached. Any attempt to push
146 more buffers into the queue will block the pushing thread until more space
147 becomes available. <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-buffers" title='The "extra-size-buffers" property'><span class="type">"extra-size-buffers"</span></a>,
150 <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-bytes" title='The "extra-size-bytes" property'><span class="type">"extra-size-bytes"</span></a> and <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-time" title='The "extra-size-time" property'><span class="type">"extra-size-time"</span></a> are
154 The default queue size limits are 5 buffers, 10MB of data, or
155 two second worth of data, whichever is reached first. Note that the number
156 of buffers will dynamically grow depending on the fill level of
160 The <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-underrun" title='The "underrun" signal'><span class="type">"underrun"</span></a> signal is emitted when all of the queues
161 are empty. The <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-overrun" title='The "overrun" signal'><span class="type">"overrun"</span></a> signal is emitted when one of the
163 Both signals are emitted from the context of the streaming thread.
169 Last reviewed on 2008-01-25 (0.10.17)
171 <div class="refsynopsisdiv">
173 <div class="refsect2">
174 <a name="idp10450544"></a><h3>Element Information</h3>
175 <div class="variablelist"><table border="0">
176 <col align="left" valign="top">
179 <td><p><span class="term">plugin</span></p></td>
181 <a class="link" href="gstreamer-plugins-plugin-coreelements.html#plugin-coreelements">coreelements</a>
185 <td><p><span class="term">author</span></p></td>
186 <td>Edward Hervey <edward@fluendo.com></td>
189 <td><p><span class="term">class</span></p></td>
196 <div class="refsect2">
197 <a name="idp10458000"></a><h3>Element Pads</h3>
198 <div class="variablelist"><table border="0">
199 <col align="left" valign="top">
202 <td><p><span class="term">name</span></p></td>
206 <td><p><span class="term">direction</span></p></td>
210 <td><p><span class="term">presence</span></p></td>
214 <td><p><span class="term">details</span></p></td>
219 <div class="variablelist"><table border="0">
220 <col align="left" valign="top">
223 <td><p><span class="term">name</span></p></td>
227 <td><p><span class="term">direction</span></p></td>
231 <td><p><span class="term">presence</span></p></td>
235 <td><p><span class="term">details</span></p></td>
245 <div class="refsect1">
246 <a name="gstreamer-plugins-multiqueue.details"></a><h2>Details</h2>
247 <div class="refsect2">
248 <a name="GstMultiQueue-struct"></a><h3>struct GstMultiQueue</h3>
249 <pre class="programlisting">struct GstMultiQueue;</pre>
251 Opaque <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> structure.
255 <div class="refsect1">
256 <a name="gstreamer-plugins-multiqueue.property-details"></a><h2>Property Details</h2>
257 <div class="refsect2">
258 <a name="GstMultiQueue--extra-size-buffers"></a><h3>The <code class="literal">"extra-size-buffers"</code> property</h3>
259 <pre class="programlisting"> "extra-size-buffers" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write</pre>
260 <p>Amount of buffers the queues can grow if one of them is empty (0=disable) (NOT IMPLEMENTED).</p>
261 <p>Default value: 5</p>
264 <div class="refsect2">
265 <a name="GstMultiQueue--extra-size-bytes"></a><h3>The <code class="literal">"extra-size-bytes"</code> property</h3>
266 <pre class="programlisting"> "extra-size-bytes" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write</pre>
267 <p>Amount of data the queues can grow if one of them is empty (bytes, 0=disable) (NOT IMPLEMENTED).</p>
268 <p>Default value: 10485760</p>
271 <div class="refsect2">
272 <a name="GstMultiQueue--extra-size-time"></a><h3>The <code class="literal">"extra-size-time"</code> property</h3>
273 <pre class="programlisting"> "extra-size-time" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a> : Read / Write</pre>
274 <p>Amount of time the queues can grow if one of them is empty (in ns, 0=disable) (NOT IMPLEMENTED).</p>
275 <p>Default value: 3000000000</p>
278 <div class="refsect2">
279 <a name="GstMultiQueue--max-size-buffers"></a><h3>The <code class="literal">"max-size-buffers"</code> property</h3>
280 <pre class="programlisting"> "max-size-buffers" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write</pre>
281 <p>Max. number of buffers in the queue (0=disable).</p>
282 <p>Default value: 5</p>
285 <div class="refsect2">
286 <a name="GstMultiQueue--max-size-bytes"></a><h3>The <code class="literal">"max-size-bytes"</code> property</h3>
287 <pre class="programlisting"> "max-size-bytes" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a> : Read / Write</pre>
288 <p>Max. amount of data in the queue (bytes, 0=disable).</p>
289 <p>Default value: 10485760</p>
292 <div class="refsect2">
293 <a name="GstMultiQueue--max-size-time"></a><h3>The <code class="literal">"max-size-time"</code> property</h3>
294 <pre class="programlisting"> "max-size-time" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a> : Read / Write</pre>
295 <p>Max. amount of data in the queue (in ns, 0=disable).</p>
296 <p>Default value: 2000000000</p>
299 <div class="refsect2">
300 <a name="GstMultiQueue--high-percent"></a><h3>The <code class="literal">"high-percent"</code> property</h3>
301 <pre class="programlisting"> "high-percent" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write</pre>
303 High threshold percent for buffering to finish.
305 <p>Allowed values: [0,100]</p>
306 <p>Default value: 99</p>
307 <p class="since">Since 0.10.26</p>
310 <div class="refsect2">
311 <a name="GstMultiQueue--low-percent"></a><h3>The <code class="literal">"low-percent"</code> property</h3>
312 <pre class="programlisting"> "low-percent" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a> : Read / Write</pre>
314 Low threshold percent for buffering to start.
316 <p>Allowed values: [0,100]</p>
317 <p>Default value: 10</p>
318 <p class="since">Since 0.10.26</p>
321 <div class="refsect2">
322 <a name="GstMultiQueue--use-buffering"></a><h3>The <code class="literal">"use-buffering"</code> property</h3>
323 <pre class="programlisting"> "use-buffering" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a> : Read / Write</pre>
325 Enable the buffering option in multiqueue so that BUFFERING messages are
326 emited based on low-/high-percent thresholds.
328 <p>Default value: FALSE</p>
329 <p class="since">Since 0.10.26</p>
332 <div class="refsect1">
333 <a name="gstreamer-plugins-multiqueue.signal-details"></a><h2>Signal Details</h2>
334 <div class="refsect2">
335 <a name="GstMultiQueue-overrun"></a><h3>The <code class="literal">"overrun"</code> signal</h3>
336 <pre class="programlisting"><span class="returnvalue">void</span> user_function (<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> *multiqueue,
337 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data) : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a></pre>
339 Reports that one of the queues in the multiqueue is full (overrun).
340 A queue is full if the total amount of data inside it (num-buffers, time,
341 size) is higher than the boundary values which can be set through the
345 This can be used as an indicator of pre-roll.
347 <div class="variablelist"><table border="0">
348 <col align="left" valign="top">
351 <td><p><span class="term"><em class="parameter"><code>multiqueue</code></em> :</span></p></td>
352 <td>the multiqueue instance</td>
355 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
356 <td>user data set when the signal handler was connected.</td>
362 <div class="refsect2">
363 <a name="GstMultiQueue-underrun"></a><h3>The <code class="literal">"underrun"</code> signal</h3>
364 <pre class="programlisting"><span class="returnvalue">void</span> user_function (<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> *multiqueue,
365 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data) : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a></pre>
367 This signal is emitted from the streaming thread when there is
368 no data in any of the queues inside the multiqueue instance (underrun).
371 This indicates either starvation or EOS from the upstream data sources.
373 <div class="variablelist"><table border="0">
374 <col align="left" valign="top">
377 <td><p><span class="term"><em class="parameter"><code>multiqueue</code></em> :</span></p></td>
378 <td>the multqueue instance</td>
381 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
382 <td>user data set when the signal handler was connected.</td>
388 <div class="refsect1">
389 <a name="gstreamer-plugins-multiqueue.see-also"></a><h2>See Also</h2>
390 <a class="link" href="gstreamer-plugins-queue.html#GstQueue"><span class="type">GstQueue</span></a>
395 Generated by GTK-Doc V1.17</div>