gstreamer/docs/manual/advanced-threads.xml

101 lines
4.3 KiB
XML
Raw Normal View History

<chapter id="chapter-threads">
<title>Threads</title>
<para>
&GStreamer; is inherently multi-threaded, and is fully thread-safe.
Most threading internals are hidden from the application, which should
make application development easier. However, in some cases, applications
may want to have influence on some parts of those. &GStreamer; allows
applications to force the use of multiple threads over some parts of
a pipeline.
</para>
<sect1 id="section-threads-uses">
<title>When would you want to force a thread?</title>
<para>
There are several reasons to force the use of threads. However,
for performance reasons, you never want to use one thread for every
element out there, since that will create some overhead.
Let's now list some situations where threads can be particularly
useful:
</para>
<itemizedlist>
<listitem>
<para>
Data buffering, for example when dealing with network streams or
when recording data from a live stream such as a video or audio
card. Short hickups elsewhere in the pipeline will not cause data
loss.
</para>
<figure float="1" id="section-thread-buffering-img">
<title>Data buffering, from a networked source</title>
<mediaobject>
<imageobject>
<imagedata scale="75" fileref="images/thread-buffering.&image;" format="&IMAGE;"/>
</imageobject>
</mediaobject>
</figure>
</listitem>
<listitem>
<para>
Synchronizing output devices, e.g. when playing a stream containing
both video and audio data. By using threads for both outputs, they
will run independently and their synchronization will be better.
</para>
<figure float="1" id="section-thread-synchronizing-img">
<title>Synchronizing audio and video sinks</title>
<mediaobject>
<imageobject>
<imagedata scale="75" fileref="images/thread-synchronizing.&image;" format="&IMAGE;"/>
</imageobject>
</mediaobject>
</figure>
</listitem>
</itemizedlist>
docs/manual/: Add scale factor for pdf output. Original commit message from CVS: patch by: Luc Pionchon <luc.pionchon@nokia.com> * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-threads.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: Add scale factor for pdf output. * docs/manual/intro-basics.xml: Switched sections "pads" and "bins" and added a pipeline diagram. * docs/manual/intro-gstreamer.xml: Added more info on gstreamer. * docs/manual/intro-motivation.xml: Commented out the whole section "current problem", which sounds historical and somehow osolete; it could be turned in a positive way and reused to improve the design principles. * docs/manual/intro-preface.xml: - Update URLs to library.gnome.org. - Do not mention GTK+ in preliminary reading (irrelevant). - Mention Plugin Writer's Manual and further reading only in the previous section. - Added a list of most relevant GObject/glib topics. * docs/manual/Makefile.am: * docs/manual/bin-element-ghost.fig: * docs/manual/bin-element-ghost.png: * docs/manual/bin-element-noghost.fig: * docs/manual/bin-element-noghost.png: * docs/manual/bin-element.fig: * docs/manual/bin-element.png: * docs/manual/filter-element-multi.fig: * docs/manual/filter-element-multi.png: * docs/manual/filter-element.fig: * docs/manual/filter-element.png: * docs/manual/gstreamer-overview.png: * docs/manual/hello-world.fig: * docs/manual/hello-world.png: * docs/manual/linked-elements.fig: * docs/manual/linked-elements.png: * docs/manual/mime-world.fig: * docs/manual/mime-world.png: * docs/manual/queue.fig: * docs/manual/queue.png: * docs/manual/simple-player.png: * docs/manual/sink-element.fig: * docs/manual/sink-element.png: * docs/manual/src-element.fig: * docs/manual/src-element.png: * docs/manual/diagrams-general.svg: * docs/manual/diagrams-pipelines.svg: Removed .fig, added .png counterpart. Fixes: #539137
2008-06-27 07:03:05 +00:00
<para>
Above, we've mentioned the <quote>queue</quote> element several times
now. A queue is the thread boundary element through which you can
force the use of threads. It does so by using a classic
provider/receiver model as learned in threading classes at
universities all around the world. By doing this, it acts both as a
means to make data throughput between threads threadsafe, and it can
also act as a buffer. Queues have several <classname>GObject</classname>
properties to be configured for specific uses. For example, you can set
lower and upper tresholds for the element. If there's less data than
the lower treshold (default: disabled), it will block output. If
there's more data than the upper treshold, it will block input or
(if configured to do so) drop data.
</para>
<para>
To use a queues (and therefore force the use of two distinct threads
in the pipeline), one can simply create a <quote>queue</quote> element
and put this in as part of the pipeline. &GStreamer; will take care of
all threading details internally.
</para>
</sect1>
<sect1 id="section-threads-scheduling">
<title>Scheduling in &GStreamer;</title>
<para>
Scheduling of pipelines in &GStreamer; is done by using a thread for
each <quote>group</quote>, where a group is a set of elements separated
by <quote>queue</quote> elements. Within such a group, scheduling is
either push-based or pull-based, depending on which mode is supported
by the particular element. If elements support random access to data,
such as file sources, then elements downstream in the pipeline become
the entry point of this group (i.e. the element controlling the
scheduling of other elements). The entry point pulls data from upstream
and pushes data downstream, thereby calling data handling functions on
either type of element.
</para>
<para>
In practice, most elements in &GStreamer;, such as decoders, encoders,
etc. only support push-based scheduling, which means that in practice,
&GStreamer; uses a push-based scheduling model.
</para>
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
</sect1>
</chapter>