gstreamer/docs/manual/cothreads.xml
Stefan Kost 626cbdc8b2 cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to R...
Original commit message from CVS:
cleanup of unused and forgoten sections
fixed links from the manual and the pwg to the API docs
added more notes to README
2004-07-27 15:01:10 +00:00

130 lines
4.5 KiB
XML

<chapter id="chapter-cothreads">
<title>Cothreads</title>
<para>
Cothreads are user-space threads that greatly reduce context switching overhead introduced by
regular kernel threads. Cothreads are also used to handle the more complex elements. They differ
from other user-space threading libraries in that they are scheduled explictly by GStreamer.
</para>
<para>
A cothread is created by a <ulink type="http"
url="../../gstreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
whenever an element is found
inside the bin that has one or more of the following properties:
<itemizedlist>
<listitem>
<para>
The element is loop-based instead of chain-based
</para>
</listitem>
<listitem>
<para>
The element has multiple input pads
</para>
</listitem>
<listitem>
<para>
The element has the MULTI_IN flag set
</para>
</listitem>
</itemizedlist>
The <ulink type="http" url="../../gstreamer/html/GstBin.html"><classname>GstBin
</classname></ulink> will create a cothread context for all the elements
in the bin so that the elements will interact in cooperative
multithreading.
</para>
<para>
Before proceding to the concept of loop-based elements we will first
explain the chain-based elements.
</para>
<sect1 id="section-chain-based">
<title>Chain-based elements</title>
<para>
Chain based elements receive a buffer of data and are supposed
to handle the data and perform a gst_pad_push.
</para>
<para>
The basic main function of a chain-based element is like:
</para>
<programlisting>
static void
chain_function (GstPad *pad, GstBuffer *buffer)
{
GstBuffer *outbuffer;
....
// process the buffer, create a new outbuffer
...
gst_pad_push (srcpad, outbuffer);
}
</programlisting>
<para>
Chain based function are mainly used for elements that have a one to one
relation between their input and output behaviour. An example of such an
element can be a simple video blur filter. The filter takes a buffer in, performs
the blur operation on it and sends out the resulting buffer.
</para>
<para>
Another element, for example, is a volume filter. The filter takes audio samples as
input, performs the volume effect and sends out the resulting buffer.
</para>
</sect1>
<sect1 id="section-loop-based">
<title>Loop-based elements</title>
<para>
As opposed to chain-based elements, loop-based elements enter an
infinite loop that looks like this:
<programlisting>
GstBuffer *buffer, *outbuffer;
while (1) {
buffer = gst_pad_pull (sinkpad);
...
// process buffer, create outbuffer
while (!done) {
....
// optionally request another buffer
buffer = gst_pad_pull (sinkpad);
....
}
...
gst_pad_push (srcpad, outbuffer);
}
</programlisting>
The loop-based elements request a buffer whenever they need one.
</para>
<para>
When the request for a buffer cannot be immediately satisfied, the control
will be given to the source element of the loop-based element until it
performs a push on its source pad. At that time the control is handed
back to the loop-based element, etc... The execution trace can get
fairly complex using cothreads when there are multiple input/output
pads for the loop-based element. Cothread switches are performed within
the call to gst_pad_pull and gst_pad_push; from the perspective of
the loop-based element, it just "appears" that gst_pad_push (or _pull)
might take a long time to return.
</para>
<para>
Loop based elements are mainly used for the more complex elements
that need a specific amount of data before they can start to produce
output. An example of such an element is the MPEG video decoder. The
element will pull a buffer, perform some decoding on it and optionally
request more buffers to decode, and when a complete video frame has
been decoded, a buffer is sent out. For example, any plugin using the
bytestream library will need to be loop-based.
</para>
<para>
There is no problem in putting cothreaded elements into a <ulink
type="http" url="../../gstreamer/html/GstThread.html"><classname>GstThread
</classname></ulink> to
create even more complex pipelines with both user and kernel space threads.
</para>
</sect1>
</chapter>