docs/manual/cothreads.xml

   1 <chapter id="cha-cothreads">
   2   <title>Cothreads</title>
   3   <para>
   4     Cothreads are user-space threads that greatly reduce context switching overhead introduced by
   5     regular kernel threads. Cothreads are also used to handle the more complex elements. They differ
   6     from other user-space threading libraries in that they are scheduled explictly by GStreamer.
   7   </para>
   8   <para>
   9     A cothread is created by a <classname>GstBin</classname> whenever an element is found
  10     inside the bin that has one or more of the following properties:
  11     <itemizedlist>
  12       <listitem>
  13         <para>
  14           The element is loop-based instead of chain-based
  15         </para>
  16       </listitem>
  17       <listitem>
  18         <para>
  19           The element has multiple input pads
  20         </para>
  21       </listitem>
  22       <listitem>
  23         <para>
  24           The element has the MULTI_IN flag set
  25         </para>
  26       </listitem>
  27     </itemizedlist>
  28     The <classname>GstBin</classname> will create a cothread context for all the elements
  29     in the bin so that the elements will interact in cooperative
  30     multithreading.
  31   </para>
  32   <para>
  33     Before proceding to the concept of loop-based elements we will first
  34     explain the chain-based elements.
  35   </para>
  36
  37   <sect1 id="sec-chain-based">
  38     <title>Chain-based elements</title>
  39     <para>
  40       Chain based elements receive a buffer of data and are supposed
  41       to handle the data and perform a gst_pad_push.
  42     </para>
  43     <para>
  44       The basic main function of a chain-based element is like:
  45     </para>
  46     <programlisting>
  47 static void
  48 chain_function (GstPad *pad, GstBuffer *buffer)
  49 {
  50   GstBuffer *outbuffer;
  51
  52   ....
  53   // process the buffer, create a new outbuffer
  54   ...
  55
  56   gst_pad_push (srcpad, outbuffer);
  57 }
  58     </programlisting>
  59     <para>
  60       Chain based function are mainly used for elements that have a one to one
  61       relation between their input and output behaviour. An example of such an
  62       element can be a simple video blur filter. The filter takes a buffer in, performs
  63       the blur operation on it and sends out the resulting buffer.
  64     </para>
  65     <para>
  66       Another element, for example, is a volume filter. The filter takes audio samples as
  67       input, performs the volume effect and sends out the resulting buffer.
  68     </para>
  69
  70   </sect1>
  71
  72   <sect1 id="sec-loop-based">
  73     <title>Loop-based elements</title>
  74     <para>
  75      As opposed to chain-based elements, loop-based elements enter an
  76      infinite loop that looks like this:
  77
  78     <programlisting>
  79   GstBuffer *buffer, *outbuffer;
  80
  81   while (1) {
  82     buffer = gst_pad_pull (sinkpad);
  83     ...
  84     // process buffer, create outbuffer
  85     while (!done) {
  86       ....
  87       // optionally request another buffer
  88       buffer = gst_pad_pull (sinkpad);
  89       ....
  90     }
  91     ...
  92     gst_pad_push (srcpad, outbuffer);
  93   }
  94     </programlisting>
  95
  96      The loop-based elements request a buffer whenever they need one.
  97     </para>
  98
  99     <para>
 100       When the request for a buffer cannot immediatly satisfied, the control
 101       will be given to the source element of the loop-based element until it
 102       performs a push on its source pad. At that time the control is handed
 103       back to the loop-based element, etc... The execution trace can get
 104       fairly complex using cothreads when there are multiple input/output
 105       pads for the loop-based element. Cothread switches are performed within
 106       the call to gst_pad_pull and gst_pad_push; from the perspective of
 107       the loop-based element, it just "appears" that gst_pad_push (or _pull)
 108       might take a long time to return.
 109     </para>
 110     <para>
 111       Loop based elements are mainly used for the more complex elements
 112       that need a specific amount of data before they can start to produce
 113       output. An example of such an element is the MPEG video decoder. The
 114       element will pull a buffer, perform some decoding on it and optionally
 115       request more buffers to decode, and when a complete video frame has
 116       been decoded, a buffer is sent out. For example, any plugin using the
 117       bytestream library will need to be loop-based.
 118     </para>
 119     <para>
 120       There is no problem in putting cothreaded elements into a <classname>GstThread</classname> to
 121       create even more complex pipelines with both user and kernel space threads.
 122     </para>
 123
 124   </sect1>
 125 </chapter>