From a43156d77c7137f405836bba7837d6898b1de2ff Mon Sep 17 00:00:00 2001 From: eschnett Date: Tue, 26 Feb 2013 03:19:48 +0000 Subject: Implement CCTK_Error and friends git-svn-id: http://svn.cactuscode.org/flesh/trunk@4964 17b73243-c579-4c4c-a9d2-2d5706c11dac --- doc/ReferenceManual.pdf | Bin 771464 -> 783628 bytes doc/ReferenceManual/CCTKReference.tex | 322 +++++++++++++++++++++++++++++++--- doc/UsersGuide.pdf | Bin 716646 -> 716732 bytes doc/UsersGuide/ApplicationThorns.tex | 48 +++-- 4 files changed, 319 insertions(+), 51 deletions(-) diff --git a/doc/ReferenceManual.pdf b/doc/ReferenceManual.pdf index d511d43e..e7e77621 100644 Binary files a/doc/ReferenceManual.pdf and b/doc/ReferenceManual.pdf differ diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex index bd617ef2..5900e180 100644 --- a/doc/ReferenceManual/CCTKReference.tex +++ b/doc/ReferenceManual/CCTKReference.tex @@ -198,6 +198,10 @@ from Fortran. Check a STRING or KEYWORD parameter for equality equality with a given string +\item[\code{CCTK\_ERROR}] [\pageref{CCTK-ERROR}] + Macro to print a single string as error message to standard error + and stop the code + \item[\code{CCTK\_Exit}] [\pageref{CCTK-Exit}] Causes normal Cactus termination @@ -829,6 +833,10 @@ from Fortran. \item[\code{CCTK\_VarTypeSize}] [\pageref{CCTK-VarTypeSize}] Provides variable type size in bytes from the variable type index +\item[\code{CCTK\_VError}] [\pageref{CCTK-VError}] + Prints a formatted string with a variable argument list as error + message to standard error and stops the code + \item[\code{CCTK\_VInfo}] [\pageref{CCTK-VInfo}] Prints a formatted string with a variable argument list as an information message to screen @@ -902,16 +910,20 @@ It never returns to the caller. \begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} Exit the code cleanly \end{SeeAlso2} -\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN} -Macro to print a single string as a warning message and possibly stop the code +\begin{SeeAlso2}{CCTK\_ERROR}{CCTK-ERROR} +Macro to print a single string as error message and stop the code \end{SeeAlso2} -\begin{SeeAlso2}{CCTK\_Warn}{CCTK-WARN} -Prints a single string as a warning message and possibly stops the code +\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError} +Prints a formatted string with a variable argument list as error +message to standard error and stops the code \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn} Prints a formatted string with a variable argument list as a warning message to standard error and possibly stops the code \end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN} +Macro to print a single string as a warning message and possibly stop the code +\end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} @@ -2967,6 +2979,103 @@ end subroutine MyThorn_some_routine \end{ExampleSection} \end{FunctionDescription} +% WarnLevel.c +%Entering a function description for CCTK_ERROR +\begin{FunctionDescription}{CCTK\_ERROR} +\label{CCTK-ERROR} +Macro to print a single string as error message and stop the code + +\begin{SynopsisSection} +\begin{Synopsis}{C} +\begin{verbatim} +#include + +CCTK_ERROR(const char *message); +\end{verbatim} +\end{Synopsis} +\begin{Synopsis}{Fortran} +\begin{verbatim} +#include "cctk.h" + +call CCTK_ERROR(message) +character*(*) message +\end{verbatim} +\end{Synopsis} +\end{SynopsisSection} + +\begin{ParameterSection} +\begin{Parameter}{message} +The error message to print +\end{Parameter} +\end{ParameterSection} + +\begin{Discussion} +This macro can be used by thorns to print a single string as error +message to \code{stderr}. + +\code{CCTK\_ERROR(message)} expands to a call to an internal function +which is equivalent to \verb|CCTK_VError()|, but without the +variable-number-of-arguments feature (so it can be used from +Fortran).%%% +\footnote{%%% + Some code calls this internal function directly. + For reference, the function is:\\ + \texttt{\hbox{}void CCTK\_Error(int line\_number, const char* file\_name, const char* thorn\_name,}\\ + \texttt{\hbox{}~~~~~~~~~~~~~~const char* message)} + }%%% +{} The macro automatically includes details about the origin of the warning +(the thorn name, the source code file name and the line number where the macro +occurs). + +To include variables in the error message from C, you can use the routine +\code{CCTK\_VError} which accepts a variable argument list. +To include variables from Fortran, a string must be constructed and passed +in a \code{CCTK\_ERROR} macro. +\end{Discussion} + +\begin{SeeAlsoSection} +\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort} +Abort the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} +Exit the code cleanly +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError} +prints an error message with a variable argument list +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn} +Prints a formatted string with a variable argument list as a warning +message to standard error and possibly stops the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN} +Macro to print a single string as a warning message and possibly stop the code +\end{SeeAlso2} +\end{SeeAlsoSection} + +\begin{ExampleSection} +\begin{Example}{C} +\begin{verbatim} +#include + +CCTK_ERROR("Divide by 0"); +\end{verbatim} +\end{Example} +\begin{Example}{Fortran} +\begin{verbatim} +#include "cctk.h" + +integer myint +CCTK_REAL myreal +character*200 message + +write(message, '(A32, G12.7, A5, I8)') +& 'Your error message, including ', myreal, ' and ', myint +call CCTK_ERROR(message) +\end{verbatim} +\end{Example} +\end{ExampleSection} +\end{FunctionDescription} + % CommOverloadables.c \begin{FunctionDescription}{CCTK\_Exit}{Exit the code cleanly} \label{CCTK-Exit} @@ -2994,6 +3103,25 @@ the return code to abort with This routine causes an immediate, regular termination of Cactus. It never returns to the caller. \end{Discussion} +\begin{SeeAlsoSection} +\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort} +Abort the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_ERROR}{CCTK-ERROR} +Macro to print a single string as error message and stop the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError} +Prints a formatted string with a variable argument list as error +message to standard error and stops the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn} +Prints a formatted string with a variable argument list as a warning +message to standard error and possibly stops the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN} +Macro to print a single string as a warning message and possibly stop the code +\end{SeeAlso2} +\end{SeeAlsoSection} \end{FunctionDescription} @@ -5784,8 +5912,7 @@ Macro to print a single string as an information message to screen \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include CCTK_INFO(const char *message); \end{verbatim} @@ -5828,17 +5955,31 @@ in a \code{CCTK\_INFO} macro. \end{Discussion} \begin{SeeAlsoSection} -\begin{SeeAlso}{CCTK\_VInfo()} +\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR} +macro to print an error message with a single string argument and stop +the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError} +prints a formatted string with a variable argument list as error +message and stops the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo} prints a formatted string with a variable argument list as an info message to screen -\end{SeeAlso} +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn} +prints a warning message with a variable argument list +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN} +macro to print a warning message with a single string argument and +possibly stop the code +\end{SeeAlso2} \end{SeeAlsoSection} \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarningLevel.h" +#include CCTK_INFO("Output is disabled"); \end{verbatim} @@ -5866,8 +6007,7 @@ addition to printing them to screen \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include CCTK_InfoCallbackRegister(void *data, cctk_infofunc callback); @@ -12805,6 +12945,87 @@ function returns the size in bytes of the corresponding data type \end{FunctionDescription} +%Entering a function description for CCTK_VError +\begin{FunctionDescription}{CCTK\_VError} +\label{CCTK-VError} +Prints a formatted string with a variable argument list as error +message and stops the code + +\begin{SynopsisSection} +\begin{Synopsis}{C} +\begin{verbatim} +#include + +void CCTK_VError(int line, + const char *file, + const char *thorn, + const char *format, + ...); +\end{verbatim} +\end{Synopsis} +\end{SynopsisSection} + +\begin{ParameterSection} +\begin{Parameter}{line} +The line number in the originating source file where the \code{CCTK\_VError} call +occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here. +\end{Parameter} +\begin{Parameter}{file} +The file name of the originating source file where the \code{CCTK\_VError} call +occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here. +\end{Parameter} +\begin{Parameter}{thorn} +The thorn name of the originating source file where the \code{CCTK\_VError} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}). +\end{Parameter} +\begin{Parameter}{format} +The \code{printf}-like format string to use for printing the warning message. +\end{Parameter} +\begin{Parameter}{...} +The variable argument list. +\end{Parameter} +\end{ParameterSection} + +\begin{Discussion} +This routine can be used by thorns to print a formatted string +followed by a variable argument list as error message to +\code{stderr}. After printing the message, Cactus aborts the run (and +\code{CCTK\_VError} does \emph{not} return to the caller). +\end{Discussion} + +\begin{SeeAlsoSection} +\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort} +Abort the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR} +macro to print an error message with a single string argument +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} +Exit the code cleanly +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn} +Possibly prints a formatted string with a variable argument list as +warning message and/or stops the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN} +macro to print a warning message with a single string argument +\end{SeeAlso2} +\end{SeeAlsoSection} + +\begin{ExampleSection} +\begin{Example}{C} +\begin{verbatim} +#include + +const char *outdir; + +CCTK_VError(__LINE__, __FILE__, CCTK_THORNSTRING, + "Output directory '%s' could not be created", outdir); +\end{verbatim} +\end{Example} +\end{ExampleSection} +\end{FunctionDescription} + + \begin{FunctionDescription}{CCTK\_VInfo} \label{CCTK-VInfo} Prints a formatted string with a variable argument list as an info message @@ -12813,8 +13034,7 @@ to sceen \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include int status = CCTK_VInfo(const char *thorn, const char *format, @@ -12851,13 +13071,27 @@ semantics is equivalent to \code{printf}. \begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO} macro to print an info message with a single string argument \end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR} +macro to print an error message with a single string argument and stop +the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError} +prints a formatted string with a variable argument list as error +message and stops the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn} +prints a warning message with a variable argument list +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN} +macro to print a warning message with a single string argument and +possibly stop the code +\end{SeeAlso2} \end{SeeAlsoSection} \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} #include "cctk.h" -#include "cctk_WarningLevel.h" const char *outdir; @@ -12877,8 +13111,7 @@ warning message and/or stops the code \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include int status = CCTK_VWarn(int level, int line, @@ -12985,6 +13218,27 @@ print everything. \end{Discussion} \begin{SeeAlsoSection} +\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort} +Abort the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR} +macro to print an error message with a single string argument and stop +the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} +Exit the code cleanly +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO} +macro to print an info message with a single string argument +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo} +prints a formatted string with a variable argument list as an info message to +screen +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError} +prints a formatted string with a variable argument list as error +message and stops the code +\end{SeeAlso2} \begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN} macro to print a warning message with a single string argument \end{SeeAlso2} @@ -12993,8 +13247,7 @@ macro to print a warning message with a single string argument \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarningLevel.h" +#include const char *outdir; @@ -13023,8 +13276,7 @@ Macro to print a single string as a warning message and possibly stop the code \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include CCTK_WARN(int level, const char *message); \end{verbatim} @@ -13077,9 +13329,30 @@ in a \code{CCTK\_WARN} macro. \end{Discussion} \begin{SeeAlsoSection} -\begin{SeeAlso}{CCTK\_VWarn()} +\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort} +Abort the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR} +macro to print an error message with a single string argument and stop +the code +\end{SeeAlso2} +\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} +Exit the code cleanly +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO} +macro to print an info message with a single string argument +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError} +prints a formatted string with a variable argument list as error +message and stops the code +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo} +prints a formatted string with a variable argument list as an info message to +screen +\end{SeeAlso2} +\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn} prints a warning message with a variable argument list -\end{SeeAlso} +\end{SeeAlso2} \end{SeeAlsoSection} \begin{ExampleSection} @@ -13115,8 +13388,7 @@ addition to printing them to standard error \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} -#include "cctk.h" -#include "cctk_WarnLevel.h" +#include CCTK_WarnCallbackRegister(int minlevel, int maxlevel, diff --git a/doc/UsersGuide.pdf b/doc/UsersGuide.pdf index 57ae4829..e486d2ce 100644 Binary files a/doc/UsersGuide.pdf and b/doc/UsersGuide.pdf differ diff --git a/doc/UsersGuide/ApplicationThorns.tex b/doc/UsersGuide/ApplicationThorns.tex index 694d298e..8e73fd5b 100644 --- a/doc/UsersGuide/ApplicationThorns.tex +++ b/doc/UsersGuide/ApplicationThorns.tex @@ -3157,18 +3157,9 @@ But in Fortran you have to do the following call CCTK_INFO (message) \end{verbatim} -In Fortran 90, you can also do -\begin{verbatim} - integer myint - character(200) message - - write (message, '("The integer is ",i4)') myint - call CCTK_INFO (message) -\end{verbatim} - Note that \begin{itemize} -\item{} \texttt{CCTK\_INFO} is just a macro which expands to a call to +\item{} \texttt{CCTK\_INFO} is a macro which expands to a call to the internal function \texttt{CCTK\_Info()} and automatically includes the thorn name in function call. @@ -3184,6 +3175,10 @@ Note that \subsection{Error Handling, Warnings and Code Termination} \subsectionmark{Error handling, ...} \label{sec:erhawancote} +The Cactus function \texttt{CCTK\_VError()}, and its accompanying +\texttt{CCTK\_ERROR} macro, should be used to output error messages +and abort the code. + The Cactus function \texttt{CCTK\_VWarn()}, and its accompanying \texttt{CCTK\_WARN} macro, should be used to issue warning messages during code execution. @@ -3232,16 +3227,25 @@ The syntax from Fortran is \begin{verbatim} call CCTK_WARN(CCTK_WARN_ALERT, "Your warning message") \end{verbatim} +\begin{verbatim} + call CCTK_ERROR("Your error message") +\end{verbatim} and from C \begin{verbatim} CCTK_WARN(CCTK_WARN_ALERT, "Your warning message"); \end{verbatim} +\begin{verbatim} + CCTK_ERROR("Your error message"); +\end{verbatim} -Note that \texttt{CCTK\_WARN} is just a macro which expands to a call -to an internal function. The macro automatically includes the thorn name, the source code file name and line number in the message.%%% +Note that \texttt{CCTK\_ERROR} and \texttt{CCTK\_WARN} are macros +which expand to calls to an internal function. The macros +automatically include the thorn name, the source code file name and +line number in the message.%%% \footnote{%%% - In calling \texttt{CCTK\_VWarn()}, you need to + In calling \texttt{CCTK\_VError()} or \texttt{CCTK\_VWarn()}, + you need to provide this information yourself. Cactus provides the macro \texttt{CCTK\_THORNSTRING}, which is the character-string name of the @@ -3259,9 +3263,11 @@ source file name and line number will be printed to standard error along with the originating processor number, the thorn name and the warning message. The default is to omit the source file name and line number. -Note that the routine \texttt{CCTK\_VWarn()} can only be called from C, because +Note that the routines \texttt{CCTK\_VError()} and +\texttt{CCTK\_VWarn()} can only be called from C, because Fortran doesn't know about variable argument lists. So including variables in -the warning message using \texttt{CCTK\_WARN}, is currently more tricky, since +the warning message using \texttt{CCTK\_ERROR} or \texttt{CCTK\_WARN}, +is currently more tricky since you need to build the string to be output. For example, in C you would just write @@ -3284,17 +3290,7 @@ But in Fortran you have to do the following call CCTK_WARN (CCTK_WARN_ALERT, message) \end{verbatim} -In Fortran 90, you can also do -\begin{verbatim} - integer myint - real myreal - character(200) message - - write (message, '("Your warning message, including ",g12.7," and ",i8)') myreal, myint - call CCTK_WARN (CCTK_WARN_ALERT, message) -\end{verbatim} - -Besides the default methods to handle warning and information +Beside the default methods to handle error, warning, and information messages, the flesh also implements a callback scheme to let thorn writers get information and warning messages as they are produced.\footnote{For the moment, these functions can only be used from C.} -- cgit v1.2.3