You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
238 lines
7.2 KiB
TeX
238 lines
7.2 KiB
TeX
|
|
|
|
\section{Error handling}
|
|
|
|
The PSBLAS library error handling policy has been completely rewritten
|
|
in version 2.0. The idea behind the design of this new error handling
|
|
strategy is to keep error messages on a stack allowing the user to
|
|
trace back up to the point where the first error message has been
|
|
generated. Every routine in the PSBLAS-2.0 library has, as last
|
|
non-optional argument, an integer \verb|info| variable; whenever,
|
|
inside the routine, an error is detected, this variable is set to a
|
|
value corresponding to a specific error code. Then this error code is
|
|
also pushed on the error stack and then either control is returned to
|
|
the caller routine or the execution is aborted, depending on the users
|
|
choice. At the time when the execution is aborted, an error message is
|
|
printed on standard output with a level of verbosity than can be
|
|
chosen by the user. If the execution is not aborted, then, the caller
|
|
routine checks the value returned in the \verb|info| variable and, if
|
|
not zero, an error condition is raised. This process continues on all the
|
|
levels of nested calls until the level where the user decides to abort
|
|
the program execution.
|
|
|
|
Figure~\ref{fig:routerr} shows the layout of a generic \verb|psb_foo|
|
|
routine with respect to the PSBLAS-2.0 error handling policy. It is
|
|
possible to see how, whenever an error condition is detected, the
|
|
\verb|info| variable is set to the corresponding error code which is,
|
|
then, pushed on top of the stack by means of the
|
|
\verb|psb_errpush|. An error condition may be directly detected inside
|
|
a routine or indirectly checking the error code returned returned by a
|
|
called routine. Whenever an error is encountered, after it has been
|
|
pushed on stack, the program execution skips to a point where the
|
|
error condition is handled; the error condition is handled either by
|
|
returning control to the caller routine or by calling the
|
|
\verb|psb\_error| routine which prints the content of the error stack
|
|
and aborts the program execution, according to the choice made by the
|
|
user with \verb|psb_set_erraction|. The default is to print the error
|
|
and terminate the program, but the user may choose to handle the error
|
|
explicitly.
|
|
|
|
\begin{figure}[h!]
|
|
\begin{Sbox}
|
|
\begin{minipage}[tl]{0.95\textwidth}
|
|
\small
|
|
\begin{verbatim}
|
|
subroutine psb_foo(some args, info)
|
|
...
|
|
if(error detected) then
|
|
info=errcode1
|
|
call psb_errpush('psb_foo', errcode1)
|
|
goto 9999
|
|
end if
|
|
...
|
|
call psb_bar(some args, info)
|
|
if(info .ne. zero) then
|
|
info=errcode2
|
|
call psb_errpush('psb_foo', errcode2)
|
|
goto 9999
|
|
end if
|
|
...
|
|
9999 continue
|
|
if (err_act .eq. act_abort) then
|
|
call psb_error(icontxt)
|
|
return
|
|
else
|
|
return
|
|
end if
|
|
|
|
end subroutine psb_foo
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{Sbox}
|
|
\setlength{\fboxsep}{8pt}
|
|
\begin{center}
|
|
\fbox{\TheSbox}
|
|
\end{center}
|
|
\caption{\label{fig:routerr}The layout of a generic \texttt{psb\_foo}
|
|
routine with respect to PSBLAS-2.0 error handling policy.}
|
|
\end{figure}
|
|
|
|
|
|
|
|
|
|
Figure~\ref{fig:errormsg} reports a sample error message generated by
|
|
the PSBLAS-2.0 library. This error has been generated by the fact that
|
|
the user has chosen the invalid ``FOO'' storage format to represent
|
|
the sparse matrix. From this error message it is possible to see that
|
|
the error has been detected inside the \verb|psb_cest| subroutine
|
|
called by \verb|psb_spasb| ... by process 0 (i.e. the root process).
|
|
|
|
|
|
\begin{figure}[h!]
|
|
\begin{Sbox}
|
|
\begin{minipage}[tl]{0.95\textwidth}
|
|
\begin{verbatim}
|
|
==========================================================
|
|
Process: 0. PSBLAS Error (4010) in subroutine: df_sample
|
|
Error from call to subroutine mat dist
|
|
==========================================================
|
|
Process: 0. PSBLAS Error (4010) in subroutine: mat_distv
|
|
Error from call to subroutine psb_spasb
|
|
==========================================================
|
|
Process: 0. PSBLAS Error (4010) in subroutine: psb_spasb
|
|
Error from call to subroutine psb_cest
|
|
==========================================================
|
|
Process: 0. PSBLAS Error (136) in subroutine: psb_cest
|
|
Format FOO is unknown
|
|
==========================================================
|
|
Aborting...
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{Sbox}
|
|
\setlength{\fboxsep}{8pt}
|
|
\begin{center}
|
|
\fbox{\TheSbox}
|
|
\end{center}
|
|
\caption{\label{fig:errormsg}A sample PSBLAS-2.0 error
|
|
message. Process 0 detected an error condition inside the {\textrm
|
|
psb\_cest} subroutine}
|
|
\end{figure}
|
|
|
|
|
|
\clearpage\subsection*{psb\_errpush --- Pushes an error code onto the error
|
|
stack}
|
|
\addcontentsline{toc}{subsection}{psb\_errpush}
|
|
|
|
\begin{verbatim}
|
|
call psb_errpush(err_c, r_name, i_err, a_err)
|
|
\end{verbatim}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\item[\bf On Entry]
|
|
\item[err\_c] the error code\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer.
|
|
\item[r\_name] the soutine where the error has been caught.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: a string.\\
|
|
\item[i\_err] addional info for error code\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf optional}\\
|
|
Specified as: an integer array\\
|
|
\item[a\_err] addional info for error code\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf optional}\\
|
|
Specified as: a string.\\
|
|
\end{description}
|
|
|
|
\clearpage\subsection*{psb\_error --- Prints the error stack content and aborts
|
|
execution}
|
|
\addcontentsline{toc}{subsection}{psb\_error}
|
|
|
|
\begin{verbatim}
|
|
call psb_error(icontxt)
|
|
\end{verbatim}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\item[\bf On Entry]
|
|
\item[icontxt] the communication context.\\
|
|
Scope: {\bf global} \\
|
|
Type: {\bf optional}\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer.
|
|
\end{description}
|
|
|
|
|
|
|
|
\clearpage\subsection*{psb\_set\_errverbosity --- Sets the verbosity of error
|
|
messages.}
|
|
\addcontentsline{toc}{subsection}{psb\_set\_errverbosity}
|
|
|
|
\begin{verbatim}
|
|
call psb_set_errverbosity(v)
|
|
\end{verbatim}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\item[\bf On Entry]
|
|
\item[v] the verbosity level\\
|
|
Scope: {\bf global}\\
|
|
Type: {\bf required}\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer.
|
|
\end{description}
|
|
|
|
\clearpage\subsection*{psb\_set\_erraction --- Set the type of action to be
|
|
taken upon error condition.}
|
|
\addcontentsline{toc}{subsection}{psb\_set\_erraction}
|
|
|
|
|
|
\begin{verbatim}
|
|
call psb_set_erraction(err_act)
|
|
\end{verbatim}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\item[\bf On Entry]
|
|
\item[err\_act] the type of action.\\
|
|
Scope: {\bf global} \\
|
|
Type: {\bf required}\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer. Possible values: \verb|psb_act_ret|,
|
|
\verb|psb_act_abort|.
|
|
\end{description}
|
|
|
|
|
|
|
|
%% \clearpage\subsection*{psb\_errcomm --- Error communication routine}
|
|
%\addcontentsline{toc}{subsection}{psb\_errcomm}
|
|
|
|
\begin{verbatim}
|
|
call psb_errcomm(icontxt, err)
|
|
\end{verbatim}
|
|
|
|
%% \begin{description}
|
|
%% \item[\bf On Entry]
|
|
%% \item[icontxt] the communication context.\\
|
|
%% Scope: {\bf global} \\
|
|
%% Type: {\bf required}\\
|
|
%% Intent: {\bf in}.\\
|
|
%% Specified as: an integer.
|
|
%% \item[err] the error code to be communicated\\
|
|
%% Scope: {\bf global} \\
|
|
%% Type: {\bf required}\\
|
|
%% Intent: {\bf inout}.\\
|
|
%% Specified as: an integer.\\
|
|
%% \end{description}
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "userguide"
|
|
%%% End:
|