gstreamer/docs/manual/threads.sgml
Steve Baker 3cda4e2eaa sync with the current CVS glib API
Original commit message from CVS:
sync with the current CVS glib API
2001-08-13 19:00:13 +00:00

139 lines
3.6 KiB
Text

<chapter id="cha-threads">
<title>Threads</title>
<para>
GStreamer has support for multithreading throught the use of
the <classname>GstThread</classname> object. This object is in fact
a special <classname>GstBin</classname> that will become a thread when started.
</para>
<para>
To construct a new thread you will perform something like:
</para>
<programlisting>
GstElement *my_thread;
// create the thread object
my_thread = gst_thread_new ("my_thread");
g_return_if_fail (audio_thread != NULL);
// add some plugins
gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (funky_src));
gst_bin_add (GST_BIN (my_thread), GST_ELEMENT (cool_effect));
// connect the elements here...
...
// start playing
gst_element_set_state (GST_ELEMENT (my_thread), GST_STATE_PLAYING);
</programlisting>
<para>
The above program will create a thread with two elements in it. As soon
as it is set to the PLAYING state, the thread will start to iterate.
</para>
<note>
<para>
A thread should normally contain a source element. Most often, the thread
is fed with data from a queue.
</para>
</note>
<para>
A thread will be visualised as below
</para>
<figure float="1" id="sec-threads-img">
<title>a thread</title>
<graphic fileref="images/thread" format="png"></graphic>
</figure>
<para>
As an example we show the helloworld program using a thread.
</para>
<programlisting>
#include &lt;gst/gst.h&gt;
/* eos will be called when the src element has an end of stream */
void
eos (GstSrc *src, gpointer data)
{
GstThread *thread = GST_THREAD (data);
g_print ("have eos, quitting\n");
/* stop the bin */
gst_element_set_state (GST_ELEMENT (thread), GST_STATE_NULL);
gst_main_quit ();
}
int
main (int argc, char *argv[])
{
GstElement *disksrc, *audiosink;
GstElement *pipeline;
GstElement *thread;
if (argc != 2) {
g_print ("usage: &percnt;s &lt;filename&gt;\n", argv[0]);
exit (-1);
}
gst_init (&amp;argc, &amp;argv);
/* create a new thread to hold the elements */
thread = gst_thread_new ("thread");
g_assert (thread != NULL);
/* create a new bin to hold the elements */
pipeline = gst_pipeline_new ("pipeline");
g_assert (pipeline != NULL);
/* create a disk reader */
disksrc = gst_elementfactory_make ("disksrc", "disk_source");
g_assert (disksrc != NULL);
g_object_set (G_OBJECT (disksrc), "location", argv[1], NULL);
g_signal_connect (G_OBJECT (disksrc), "eos",
G_CALLBACK (eos), thread);
/* and an audio sink */
audiosink = gst_elementfactory_make ("audiosink", "play_audio");
g_assert (audiosink != NULL);
/* add objects to the main pipeline */
gst_bin_add (GST_BIN (pipeline), disksrc);
gst_bin_add (GST_BIN (pipeline), audiosink);
/* automatically setup the pipeline */
if (!gst_pipeline_autoplug (GST_PIPELINE (pipeline))) {
g_print ("unable to handle stream\n");
exit (-1);
}
/* remove the source element from the pipeline */
gst_bin_remove (GST_BIN (pipeline), disksrc);
/* insert the source element in the thread, remember a thread needs at
least one source or connection element */
gst_bin_add (GST_BIN (thread), disksrc);
/* add the pipeline to the thread too */
gst_bin_add (GST_BIN (thread), GST_ELEMENT (pipeline));
/* start playing */
gst_element_set_state (GST_ELEMENT (thread), GST_STATE_PLAYING);
/* do whatever you want here, the thread will be playing */
...
gst_main ();
gst_pipeline_destroy (thread);
exit (0);
}
</programlisting>
</chapter>