*** empty log message ***
Alfredo Buttari
19 years ago
parent
22457aba9f
commit
be441c71a9
@ -0,0 +1,201 @@
|
||||
\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, en 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.
|
||||
|
||||
\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}
|
||||
|
||||
|
||||
\subroutine{psb\_errpush}{Pushes an error code onto the error stack}
|
||||
|
||||
\syntax{call psb\_errpush}{err\_c, r\_name, i\_err, a\_err}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[err\_c] the error code\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\item[r\_name] the soutine where the error has been caught.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
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}
|
||||
|
||||
\subroutine{psb\_error}{Prints the error stack content and aborts execution}
|
||||
|
||||
\syntax{call psb\_error}{icontxt}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[icontxt] the communication context.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_set\_errverbosity}{Sets the verbosity of error messages.}
|
||||
|
||||
\syntax{call psb\_set\_errverbosity}{v}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[v] the verbosity level\\
|
||||
Scope: {\bf global}\\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
\subroutine{psb\_set\_erraction}{Set the type of action to be taken
|
||||
upon error condition.}
|
||||
|
||||
\syntax{call psb\_set\_erraction}{err\_act}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[err\_act] the type of action.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_errcomm}{Error communication routine}
|
||||
|
||||
\syntax{call psb\_errcomm}{icontxt, err}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[icontxt] the communication context.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\item[err] the error code to be communicated\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.\\
|
||||
\end{description}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "userguide"
|
||||
%%% End:
|
||||
Loading…
Reference in New Issue