docs/manual/advanced-threads.xml

   1 <chapter id="chapter-threads">
   2   <title>Threads</title>
   3   <para>
   4     &GStreamer; is inherently multi-threaded, and is fully thread-safe.
   5     Most threading internals are hidden from the application, which should
   6     make application development easier. However, in some cases, applications
   7     may want to have influence on some parts of those. &GStreamer; allows
   8     applications to force the use of multiple threads over some parts of
   9     a pipeline.
  10   </para>
  11
  12   <sect1 id="section-threads-uses">
  13     <title>When would you want to force a thread?</title>
  14     <para>
  15       There are several reasons to force the use of threads. However,
  16       for performance reasons, you never want to use one thread for every
  17       element out there, since that will create some overhead.
  18       Let's now list some situations where threads can be particularly
  19       useful:
  20     </para>
  21     <itemizedlist>
  22       <listitem>
  23         <para>
  24           Data buffering, for example when dealing with network streams or
  25           when recording data from a live stream such as a video or audio
  26           card. Short hickups elsewhere in the pipeline will not cause data
  27           loss.
  28         </para>
  29         <figure float="1" id="section-thread-buffering-img">
  30           <title>Data buffering, from a networked source</title>
  31           <mediaobject>
  32             <imageobject>
  33               <imagedata scale="75" fileref="images/thread-buffering.&image;" format="&IMAGE;"/>
  34             </imageobject>
  35           </mediaobject>
  36         </figure>
  37
  38       </listitem>
  39       <listitem>
  40         <para>
  41           Synchronizing output devices, e.g. when playing a stream containing
  42           both video and audio data. By using threads for both outputs, they
  43           will run independently and their synchronization will be better.
  44         </para>
  45         <figure float="1" id="section-thread-synchronizing-img">
  46           <title>Synchronizing audio and video sinks</title>
  47           <mediaobject>
  48             <imageobject>
  49               <imagedata scale="75" fileref="images/thread-synchronizing.&image;" format="&IMAGE;"/>
  50             </imageobject>
  51           </mediaobject>
  52         </figure>
  53       </listitem>
  54     </itemizedlist>
  55
  56
  57     <para>
  58       Above, we've mentioned the <quote>queue</quote> element several times
  59       now. A queue is the thread boundary element through which you can
  60       force the use of threads. It does so by using a classic
  61       provider/receiver model as learned in threading classes at
  62       universities all around the world. By doing this, it acts both as a
  63       means to make data throughput between threads threadsafe, and it can
  64       also act as a buffer. Queues have several <classname>GObject</classname>
  65       properties to be configured for specific uses. For example, you can set
  66       lower and upper tresholds for the element. If there's less data than
  67       the lower treshold (default: disabled), it will block output. If
  68       there's more data than the upper treshold, it will block input or
  69       (if configured to do so) drop data.
  70     </para>
  71     <para>
  72       To use a queue (and therefore force the use of two distinct threads
  73       in the pipeline), one can simply create a <quote>queue</quote> element
  74       and put this in as part of the pipeline. &GStreamer; will take care of
  75       all threading details internally.
  76     </para>
  77   </sect1>
  78
  79   <sect1 id="section-threads-scheduling">
  80     <title>Scheduling in &GStreamer;</title>
  81
  82     <para>
  83       Scheduling of pipelines in &GStreamer; is done by using a thread for
  84       each <quote>group</quote>, where a group is a set of elements separated
  85       by <quote>queue</quote> elements. Within such a group, scheduling is
  86       either push-based or pull-based, depending on which mode is supported
  87       by the particular element. If elements support random access to data,
  88       such as file sources, then elements downstream in the pipeline become
  89       the entry point of this group (i.e. the element controlling the
  90       scheduling of other elements). The entry point pulls data from upstream
  91       and pushes data downstream, thereby calling data handling functions on
  92       either type of element.
  93     </para>
  94     <para>
  95       In practice, most elements in &GStreamer;, such as decoders, encoders,
  96       etc. only support push-based scheduling, which means that in practice,
  97       &GStreamer; uses a push-based scheduling model.
  98     </para>
  99   </sect1>
 100 </chapter>