%
% threads.tex: description of threads interface for VideoLAN client
% (c)1999 VideoLAN
%
\section{A common thread interface}

This document describes how the different threads in the VideoLAN client are
organized, their API and functionnment.

%
% Thread properties
%
\subsection{Thread properties}

A thread is described by a \csymbol{X\_thread\_t} structure (i.e. 
\csymbol{vout\_thread\_t}), which is used to reference the thread in calls to 
its API. This structure includes beside following thread-specific data the 
following fields:

\begin{csource}
typedef struct X_thread_s \{
    pthread_t   thread_id;          /* thread id for pthreads */
    boolean_t   b_die;              /* `die' flag */
    boolean_t   b_run;              /* `run' flag */
    boolean_t   b_error;            /* `error' flag */
    boolean_t   b_active;           /* `active' flag */

    ... other fields ...
\} X_thread_t;
\end{csource}

%
% Meaning of common flags
%
\subsection{Meaning of common flags}

\begin{description}
\item[\csymbol{die}]:
The \csymbol{die} flag means that the thread received a destruction request 
from  another thread. It must terminate as soon as possible. This field is 
written (set to 1) by other threads and read by the thread itself. It cannot 
be reset to 0 once it has been set.

Note that when the \csymbol{die} flag is set, no other thread should feed the 
dying one, and all shared structures should have been freed (i.e. the images 
and video streams for the video output thread).

\item[\csymbol{run}]:
The \csymbol{run} flag tells the other threads that the concerned thread is 
ready to receive data. It is set to 1 by the thread itself when the second 
phase of the initialization has succeeded, and set to 0 again by the thread 
once it exited.

\item[\csymbol{error}]:
The \csymbol{error} flag tells the other threads that a fatal error occured in
the concerned thread. It can be set by all threads, and is read by the thread
itself and the controlling thread.

When a thread is in \csymbol{error} state, it runs in a special loop, 
accepting feed from other threads, but trashing eveything, waiting for a 
\csymbol{die} signal.

Therefore, the controlling thread should check periodically if a thread has an
\csymbol{error} set and, if yes, set its \csymbol{die} flag after having 
destroyed all depending threads.

This flag is optionnal, but recommanded if an error can be envisaged in a later
extension.

\item[\csymbol{active}]:
This flag's purpose is to avoid using useless resources. An in-\csymbol{active}
thread must accept input as if it was inactive, but can treat its input 
differently.
In example: the video output thread will set itself as in-\csymbol{active} 
when it is unmapped, and continue to sort and trash images, but will not 
render or display them to avoid consumming useless CPU. When a video decoder 
thread will detect that its related output thread is inactive, it will set 
itself inactive and trash everything except I images.

The \csymbol{active} flag can be set and read by anyone. Precautions should be
taken to avoid too long wake-up times.

This flag is optionnal, but recommanded if its use can be envisaged in a later
extension.
\end{description}

%
% API
%
\subsection{API}

This API is only a recommandation.

% Creation
\subsubsection{Creation}

\begin{csource}
X_thread_t * X_CreateThread( X_cfg_t *p_cfg )
\end{csource}

This function will allocate thread descriptor, perform basic (and fast)
initialization steps, and create the thread itself using 
\csymbol{pthread\_create}.

Once it has been called, all flags are set to 0. It will return the thread 
descriptor or \csymbol{NULL} on failure.

% Termination
\subsubsection{Termination}

\begin{csource}
void X_TerminateThread( X_thread_t * p_X );
\end{csource}

This function will set the \csymbol{die} flag of the thread and and return 
immediately.

% Destruction
\subsubsection{Destruction}

\begin{csource}
int X_DestroyThread( X_thread_t *p_X );
\end{csource}

This function will try to destroy the thread descriptor, if it is possible
(if the \csymbol{run} flag is not set). It will return 0 if it succeeded, 
and non 0 if the thread was still active.

%
% Local functions names
%
\subsection{Local functions names}

The following functions names are recommanded to implement the different
parts of the thread creation and destruction:

\begin{csource}
int InitThread();       /* second phase of initialization */
int RunThread();        /* main loop */
int RunError();         /* error loop */
int DestroyThread();    /* thread destruction */
\end{csource}

\csymbol{X\_CreateThread()} will spawn a thread using \csymbol{RunThread()} 
function, which will call \csymbol{InitThread()}, enter its main loop, 
eventually call \csymbol{RunError()} and finally calls \csymbol{DestroyThread}
when \csymbol{die} is received.

%
% Order of operations
%
\subsection{Order of operations}

% Creation
\subsubsection{Creation}

\begin{tabular}{l|l}
Controlling thread                              &   Thread \\
\hline

\csymbol{p\_X = X\_CreateThread( p\_cfg )}:     & \\
    descriptor allocation and initialization    & \\
    all flags are set to 0                      & \\
    base structures initialization              & \\
If \csymbol{p\_X == NULL}: error                & \\
    \csymbol{X\_DestroyThread( p\_X )}:         & \\
        destruction of the descriptor           & \\
    end...
Else, continuation....                          & \csymbol{pthread\_create()} \\
                                                & Second step of initialization \\
                                                & On error: \\
                                                &   \csymbol{b\_error = 1} \\
                                                &   destruction of structures \\
                                                & Else: \\
                                                &   \csymbol{b\_run = 1} \\
                                                &   beginning of main loop \\

\hline

Wait for \csymbol{b\_run} or \csymbol{b\_error}...& main loop... \\
If \csymbol{b\_error}:                          & \\
    \csymbol{X\_DestroyThread( p\_X )}          & \\
    end...                                      & \\
Else (\csymbol{b\_run == 1}):                   & \\
    the thread is ready and can be feeded...    & \\

\hline
\end{tabular}

Notes:
\begin{enumerate}
\item The configuration structure can have been destroyed just after 
    \csymbol{X\_CreateThread()}. Therefore, it should not be used during second 
    initialization step.

\item When an error occurs during second initialization step, the allocated structures
    are automatically destroyed (except the thread descriptor). Therefore, a call to
    \csymbol{X\_TerminateThread} is not required.
\end{enumerate}

% Main loop
\subsubsection{Main loop}

\begin{tabular}{l|l}
Controlling thread                              &   Thread \\
\hline

Periodically check for \csymbol{b\_error}        & Periodically check for \\
If set, then:                                   & \csymbol{b\_error} and \csymbol{b\_die}\\
    terminate all dependant threads             & \\
    destroy all dependant threads               & \\
    terminate and destroy thread                & \\

\hline
\end{tabular}
 
% Destruction
\subsubsection{Destruction}

\begin{tabular}{l|l}
Controlling thread                              &   Thread \\
\hline

\csymbol{X\_TerminateThread( p\_X )}:           & \\
    set \csymbol{b\_die}                         & \\
    all flags are set to 0                      & If \csymbol{DEBUG}, check if  \\
                                                & all shared structures are ok. \\
                                                & Destroy and close everything, but  \\
                                                & keep descriptor. \\
                                                & Set \csymbol{b\_run} to 0. \\
                                                & Exit thread. \\

\hline

Loop until \csymbol{X\_DestroyThread} is 0:      & \\
    check if \csymbol{b\_run == 0}                & \\
    if yes:                                     & \\
        destroy descriptor                      & \\
        return 0                                & \\
    else:                                       & \\
        return 1                                & \\

\hline
\end{tabular}











