\section{THREADWAIT Wait on a thread to complete execution}

\subsection{Usage}

The \verb|threadwait| function waits for the given thread to complete
execution, and stops execution of the current thread (the one calling
\verb|threadwait|) until the given thread completes.  The syntax for its
use is 
\begin{verbatim}
   success = threadwait(handle)
\end{verbatim}
where \verb|handle| is the value returned by \verb|threadnew| and \verb|success|
is a \verb|logical| vaariable that will be \verb|1| if the wait was successful
or \verb|0| if the wait times out.  By default, the wait is indefinite.  It
is better to use the following form of the function
\begin{verbatim}
   success = threadwait(handle,timeout)
\end{verbatim}
where \verb|timeout| is the amount of time (in milliseconds) for 
the \verb|threadwait| function to wait before a timeout occurs.  
If the \verb|threadwait| function succeeds, then the return 
value is a logical \verb|1|, and if it fails, the return value 
is a logical \verb|0|.  Note that you can call \verb|threadwait| multiple
times on a thread, and if the thread is completed, each one
will succeed.
\subsection{Example}

Here we lauch the \verb|sleep| function in a thread with a time delay of 
10 seconds.  This means that the thread function will not complete
until 10 seconds have elapsed.  When we call \verb|threadwait| on this
thread with a short timeout, it fails, but not when the timeout
is long enough to capture the end of the function call.
\begin{verbatim}
--> a = threadnew;
--> threadstart(a,'sleep',0,10);  % start a thread that will sleep for 10
--> threadwait(a,2000)            % 2 second wait is not long enough
ans = 
  <logical>  - size: [1 1]
 0  
--> threadwait(a,10000)           % 10 second wait is long enough
ans = 
  <logical>  - size: [1 1]
 1  
--> threadfree(a)

\end{verbatim}
