\section{THREADVALUE Retrieve the return values from a thread}

\subsection{Usage}

The \verb|threadvalue| function retrieves the values returned
by the function specified in the \verb|threadnew| call.  The
syntax for its use is
\begin{verbatim}
   [arg1,arg2,...,argN] = threadvalue(handle)
\end{verbatim}
where \verb|handle| is the value returned by a \verb|threadnew| call.
Note that there are issues with \verb|nargout|.  See the examples
section of \verb|threadnew| for details on how to work around this
limitation.  Because the function you have spawned with \verb|threadnew|
may still be executing, \verb|threadvalue| must first \verb|threadwait|
for the function to complete before retrieving the output values.
This wait may take an arbitrarily long time if the thread function
is caught in an infinite loop.  Hence, you can also specify
a timeout parameter to \verb|threadvalue| as
\begin{verbatim}
   [arg1,arg2,...,argN] = threadvalue(handle,timeout)
\end{verbatim}
where the \verb|timeout| is specified in milliseconds.  If the
wait times out, an error is raised (that can be caught with a
\verb|try| and \verb|catch| block.  

In either case, if the thread function itself caused an error
and ceased execution abruptly, then calling \verb|threadvalue| will
cause that function to raise an error, allowing you to retrieve
the error that was caused and correct it.  See the examples section
for more information.
\subsection{Example}

Here we do something very simple.  We want to obtain a listing of
all files on the system, but do not want the results to stop our
computation.  So we run the \verb|system| call in a thread.
\begin{verbatim}
--> a = threadnew;                         % Create the thread
--> threadstart(a,'system',1,'ls -lrt /'); % Start the thread
--> b = rand(100)\rand(100,1);             % Solve some equations simultaneously
--> c = threadvalue(a);                    % Retrieve the file list
--> size(c)                                % It is large!

ans = 

 22  1 

--> threadfree(a);

\end{verbatim}
In this example, we force the threaded function to cause an
exception (by calling the \verb|error| function as the thread 
function).  When we call \verb|threadvalue|, we get an error, instead
of the return value of the function
\begin{verbatim}
--> a = threadnew

a = 

 3 

--> threadstart(a,'error',0,'Hello world!'); % Will immediately stop due to error
--> c = threadvalue(a)                     % The error comes to us
Error: Thread: Hello world!
--> threadfree(a)

\end{verbatim}
Note that the error has the text \verb|Thread:| prepended to the message
to help you identify that this was an error in a different thread.
