threads.xml

<chapter><title>Threading with VLC</title>

<para>VLC is a multi-thread application. We chose against a single-thread
    approach because decoder preemptibility and scheduling would be a
    mastermind (for instance decoders and outputs have to be separated,
    otherwise it cannot be warrantied that a frame will be played at the
    exact presentation time), and we currently have no plan to support a
    single-threaded client. Multi-process decoders usually imply more overhead
    (problems of shared memory) and communication between processes is harder.
    </para>


<sect1><title>VLC's threading API</title>

<para>For portability, VLC provides a wrapper for native threading API.
It is modelled on the pthread library.</para>

<para>Our wrapper consists of the following functions:</para>

<itemizedlist>
<listitem><para><function>vlc_thread_create</function></para></listitem>
<listitem><para>    <function>vlc_thread_exit</function></para></listitem>
<listitem><para>    <function>vlc_thread_join</function></para></listitem>
<listitem><para>    <function>vlc_mutex_init</function></para></listitem>
<listitem><para> <function>vlc_mutex_lock</function></para></listitem>
<listitem><para>    <function>vlc_mutex_unlock</function></para></listitem>
<listitem><para>    <function>vlc_mutex_destroy</function></para></listitem>
<listitem><para>    <function>vlc_cond_init</function></para></listitem>
<listitem><para> <function>vlc_cond_signal</function></para></listitem>
<listitem><para>    <function>vlc_cond_broadcast</function></para></listitem>
<listitem><para>    <function>vlc_cond_wait</function></para></listitem>
<listitem><para> <function>vlc_cond_destroy</function></para></listitem>
</itemizedlist>

<para>Corresponding data structures are <type>vlc_thread_t</type>,
<type>vlc_mutex_t</type>, and <type>vlc_cond_t</type>. </para>

</sect1>

</chapter>