Error Handling, Warnings and Code Termination

Error handling, ... The Cactus function CCTK_VWarn(), and its accompanying CCTK_WARN macro, should be used to issue warning messages during code execution.

Along with the warning message, an integer is given to indicate the severity of the warning. Only warnings with severity levels less than, or equal to, the global Cactus warning level threshold^part131 will be printed. A level 0 warning indicates the highest severity (and is guaranteed to abort the Cactus run), while larger numbers indicate less severe warnings. The global Cactus warning level threshold defaults to 1, level 1 warnings are printed, but level 2 and higher are not printed.

The severity level may actually be any integer, and a lot of existing code uses bare ``magic number'' integers for warning levels, but to help standardize warning levels across thorns, new code should probably use one of the following macros, defined in "cctk_WarnLevel.h" (which is #included by "cctk.h"):

#define CCTK_WARN_ABORT    0    /* abort the Cactus run */
#define CCTK_WARN_ALERT    1    /* the results of this run will probably */
                                /* be wrong, but this isn't quite certain, */
                                /* so we're not going to abort the run */
#define CCTK_WARN_COMPLAIN 2    /* the user should know about this, but */
                                /* the results of this run are probably ok */
#define CCTK_WARN_PICKY    3    /* this is for small problems that can */
                                /* probably be ignored, but that careful */
                                /* people may want to know about */
#define CCTK_WARN_DEBUG    4    /* these messages are probably useful */
                                /* only for debugging purposes */

For example, to provide a warning for a serious problem, which indicates that the results of the run are quite likely wrong, and which will be printed to the screen by default, a level CCTK_WARN_ALERT warning should be used.

The syntax from Fortran is

  call CCTK_WARN(CCTK_WARN_ALERT, "Your warning message")

and from C

  CCTK_WARN(CCTK_WARN_ALERT, "Your warning message");

Note that 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.^part132 (For this reason it is important for Fortran code that capital letters are always used in order to expand the macro.)

If the flesh parameter cctk_full_warnings is set to true, then the 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 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 CCTK_WARN, is currently more tricky, since you need to build the string to be output.

For example, in C you would just write

  int    myint;
  double myreal;

  CCTK_VWarn(CCTK_WARN_ALERT, __LINE__, __FILE__, CCTK_THORNSTRING,
             "Your warning message, including %f and %d",
             myreal, myint);

But in Fortran you have to do the following

  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)

In Fortran 90, you can also do

  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)

Besides the default methods to handle warning and information messages, the flesh also implements a callback scheme to let thorn writers get information and warning messages as they are produced.^part133

For warning messages, a function with the following prototype

void my_warnfunc(int level,
                 int line,
                 const char *file,
                 const char *thorn,
                 const char *message,
                 void *data);

should be implemented, and then registered with

CCTK_WarnCallbackRegister(int minlevel,
                          int maxlevel,
                          void *data,
                          cctk_warnfunc my_warnfunc);

The data pointer can be used to pass arbitrary information to the registered function, e.g. a file descriptor or a format string.

Multiple functions can be registered as above; when CCTK_VWarn() is called, all the registered functions will be called, if the warning is within the minimum and maximum levels indicated.

The basic procedure is exactly the same for information messages.

A function registered for information messages will look like

void my_infofunc(const char *thorn,
                 const char *message,
                 void *data);

while the registration function looks like

CCTK_InfoCallbackRegister(void *data, cctk_infofunc my_infofunc);