Actual source code: petscerror.h

  1: /*
  2:     Contains all error handling interfaces for PETSc.
  3: */

  7: #if defined(PETSC_HAVE_STRING_H)
  8: #include <string.h> /* for strcmp */
  9: #endif


 13: /*
 14:    Defines the directory where the compiled source is located; used
 15:    in printing error messages. Each makefile has an entry 
 16:    LOCDIR          =  thedirectory
 17:    and bmake/common_variables includes in CCPPFLAGS -D__SDIR__=${LOCDIR}
 18:    which is a flag passed to the C/C++ compilers. This declaration below
 19:    is only needed if some code is compiled without the -D__SDIR__
 20: */
 23: #endif

 25: /*
 26:    Defines the function where the compiled source is located; used 
 27:    in printing error messages. This is defined here in case the user
 28:    does not declare it.
 29: */
 32: #endif

 34: /* 
 35:      These are the generic error codes. These error codes are used
 36:      many different places in the PETSc source code. The string versions are
 37:      at src/sys/error/err.c any changes here must also be made there
 38:      These are also define in include/finclude/petscerror.h any CHANGES here
 39:      must be also made there.

 41: */
 42: #define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */

 44: #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
 45: #define PETSC_ERR_SUP              56   /* no support for requested operation */
 46: #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
 47: #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
 48: #define PETSC_ERR_SIG              59   /* signal received */
 49: #define PETSC_ERR_FP               72   /* floating point exception */
 50: #define PETSC_ERR_COR              74   /* corrupted PETSc object */
 51: #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
 52: #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
 53: #define PETSC_ERR_MEMC             78   /* memory corruption */
 54: #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
 55: #define PETSC_ERR_USER             83   /* user has not provided needed function */
 56: #define PETSC_ERR_SYS              88   /* error in system call */

 58: #define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
 59: #define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
 60: #define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
 61: #define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
 62: #define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
 63: #define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
 64: #define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
 65: #define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
 66: #define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
 67: #define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
 68: #define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
 69: #define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
 70: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */

 72: #define PETSC_ERR_FILE_OPEN        65   /* unable to open file */
 73: #define PETSC_ERR_FILE_READ        66   /* unable to read from file */
 74: #define PETSC_ERR_FILE_WRITE       67   /* unable to write to file */
 75: #define PETSC_ERR_FILE_UNEXPECTED  79   /* unexpected data in file */

 77: #define PETSC_ERR_MAT_LU_ZRPVT     71   /* detected a zero pivot during LU factorization */
 78: #define PETSC_ERR_MAT_CH_ZRPVT     81   /* detected a zero pivot during Cholesky factorization */

 80: #define PETSC_ERR_FLOP_COUNT       90
 81: #define PETSC_ERR_NOT_CONVERGED    91  /* solver did not converge */
 82: #define PETSC_ERR_MAX_VALUE        92  /* this is always the one more than the largest error code */

 84: #define PetscStringizeArg(a) #a
 85: #define PetscStringize(a) PetscStringizeArg(a)

 88: #if defined(PETSC_USE_ERRORCHECKING)

 90: /*MC
 91:    SETERRQ - Macro that is called when an error has been detected, 

 93:    Synopsis:
 94:    PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode errorcode,char *message)

 96:    Not Collective

 98:    Input Parameters:
 99: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
100: -  message - error message

102:   Level: beginner

104:    Notes:
105:     Once the error handler is called the calling function is then returned from with the given error code.

107:     See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments

109:     In Fortran MPI_Abort() is always called

111:     Experienced users can set the error handler with PetscPushErrorHandler().

113:    Concepts: error^setting condition

115: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
116: M*/
117: #define SETERRQ(comm,n,s)              return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s)

119: /*MC
120:    SETERRQ1 - Macro that is called when an error has been detected, 

122:    Synopsis:
123:    PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg)

125:    Not Collective

127:    Input Parameters:
128: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
129: .  message - error message in the printf format
130: -  arg - argument (for example an integer, string or double)

132:   Level: beginner

134:    Notes:
135:     Once the error handler is called the calling function is then returned from with the given error code.

137:    Experienced users can set the error handler with PetscPushErrorHandler().

139:    Concepts: error^setting condition

141: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
142: M*/
143: #define SETERRQ1(comm,n,s,a1)          return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1)

145: /*MC
146:    SETERRQ2 - Macro that is called when an error has been detected, 

148:    Synopsis:
149:    PetscErrorCode SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)

151:    Not Collective

153:    Input Parameters:
154: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
155: .  message - error message in the printf format
156: .  arg1 - argument (for example an integer, string or double)
157: -  arg2 - argument (for example an integer, string or double)

159:   Level: beginner

161:    Notes:
162:     Once the error handler is called the calling function is then returned from with the given error code.

164:    Experienced users can set the error handler with PetscPushErrorHandler().

166:    Concepts: error^setting condition

168: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
169: M*/
170: #define SETERRQ2(comm,n,s,a1,a2)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2)

172: /*MC
173:    SETERRQ3 - Macro that is called when an error has been detected, 

175:    Synopsis:
176:    PetscErrorCode SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

178:    Not Collective

180:    Input Parameters:
181: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
182: .  message - error message in the printf format
183: .  arg1 - argument (for example an integer, string or double)
184: .  arg2 - argument (for example an integer, string or double)
185: -  arg3 - argument (for example an integer, string or double)

187:   Level: beginner

189:    Notes:
190:     Once the error handler is called the calling function is then returned from with the given error code.

192:     There are also versions for 4, 5, 6 and 7 arguments.

194:    Experienced users can set the error handler with PetscPushErrorHandler().

196:    Concepts: error^setting condition

198: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
199: M*/
200: #define SETERRQ3(comm,n,s,a1,a2,a3)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3)

202: #define SETERRQ4(comm,n,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)
203: #define SETERRQ5(comm,n,s,a1,a2,a3,a4,a5)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)
204: #define SETERRQ6(comm,n,s,a1,a2,a3,a4,a5,a6)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)
205: #define SETERRQ7(comm,n,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)
206: #define SETERRABORT(comm,n,s)     do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,n);} while (0)

208: /*MC
209:    CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns

211:    Synopsis:
212:    PetscErrorCode CHKERRQ(PetscErrorCode errorcode)

214:    Not Collective

216:    Input Parameters:
217: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h

219:   Level: beginner

221:    Notes:
222:     Once the error handler is called the calling function is then returned from with the given error code.

224:     Experienced users can set the error handler with PetscPushErrorHandler().

226:     CHKERRQ(n) is fundamentally a macro replacement for
227:          if (n) return(PetscError(...,n,...));

229:     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
230:     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
231:     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
232:     you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
233:          if (n) {PetscError(....); return(YourReturnType);} 
234:     where you may pass back a PETSC_NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
235:     MPI_Abort() returned immediately.

237:     In Fortran MPI_Abort() is always called

239:    Concepts: error^setting condition

241: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
242: M*/
243: #define CHKERRQ(n)             do {if (PetscUnlikely(n)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");} while (0)

245: #define CHKERRV(n)             do {if (PetscUnlikely(n)) {n = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");return;}} while(0)
246: #define CHKERRABORT(comm,n)    do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,n);}} while (0)
247: #define CHKERRCONTINUE(n)      do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");}} while (0)

249: #ifdef PETSC_CLANGUAGE_CXX

251: /*MC
252:    CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception

254:    Synopsis:
255:    void CHKERRXX(PetscErrorCode errorcode)

257:    Not Collective

259:    Input Parameters:
260: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h

262:   Level: beginner

264:    Notes:
265:     Once the error handler throws a ??? exception.

267:     You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
268:     or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.

270:    Concepts: error^setting condition

272: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
273: M*/
274: #define CHKERRXX(n)            do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_IN_CXX,0);}} while(0)

276: #endif

278: /*MC
279:    CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected

281:    Synopsis:
282:    CHKMEMQ;

284:    Not Collective

286:   Level: beginner

288:    Notes:
289:     Must run with the option -malloc_debug to enable this option

291:     Once the error handler is called the calling function is then returned from with the given error code.

293:     By defaults prints location where memory that is corrupted was allocated.

295:     Use CHKMEMA for functions that return void

297:    Concepts: memory corruption

299: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
300:           PetscMallocValidate()
301: M*/
302: #define CHKMEMQ do {PetscErrorCode _7_PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} while(0)

304: #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__)

306: #if defined(PETSC_UNDERSCORE_CHKERR)
308: #define _   __g
310: #endif

312: #else /* PETSC_USE_ERRORCHECKING */

314: /* 
315:     These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0
316: */

318: #define SETERRQ(c,n,s) 
319: #define SETERRQ1(c,n,s,a1) 
320: #define SETERRQ2(c,n,s,a1,a2) 
321: #define SETERRQ3(c,n,s,a1,a2,a3) 
322: #define SETERRQ4(c,n,s,a1,a2,a3,a4) 
323: #define SETERRQ5(c,n,s,a1,a2,a3,a4,a5) 
324: #define SETERRQ6(c,n,s,a1,a2,a3,a4,a5,a6) 
325: #define SETERRABORT(comm,n,s) 

327: #define CHKERRQ(n)     ;
328: #define CHKERRABORT(comm,n) ;
329: #define CHKERRCONTINUE(n) ;
330: #define CHKMEMQ        ;

332: #ifdef PETSC_CLANGUAGE_CXX
333: #define CHKERRXX(n) ;
334: #endif

336: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
337: #define _   
339: #endif 

341: #endif /* PETSC_USE_ERRORCHECKING */

343: /*E
344:   PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers

346:   Level: advanced

348:   PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated

350:   Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandling()

352: .seealso: PetscError(), SETERRXX()
353: E*/
354: typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;

360: #include <sstream>
362: #endif

376: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;

379: /*
380:       Allows the code to build a stack frame as it runs
381: */
382: #if defined(PETSC_USE_DEBUG) && !defined(PETSC_USE_PTHREAD)

384: #define PETSCSTACKSIZE 64

386: typedef struct  {
387:   const char *function[PETSCSTACKSIZE];
388:   const char *file[PETSCSTACKSIZE];
389:   const char *directory[PETSCSTACKSIZE];
390:         int  line[PETSCSTACKSIZE];
391:         int currentsize;
392: } PetscStack;


398: #define PetscStackActive (petscstack != 0)

400: /*MC
402:         used for error handling.

404:    Synopsis:

407:    Not Collective

409:    Usage:
410: .vb
411:      int something;

414: .ve

416:    Notes:
417:      Not available in Fortran

419:    Level: developer

421: .seealso: PetscFunctionReturn()

423: .keywords: traceback, error handling
424: M*/
426:   do {                                                                  \
427:     if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {     \
428:       petscstack->function[petscstack->currentsize]  = PETSC_FUNCTION_NAME; \
429:       petscstack->file[petscstack->currentsize]      = __FILE__;        \
430:       petscstack->directory[petscstack->currentsize] = __SDIR__;        \
431:       petscstack->line[petscstack->currentsize]      = __LINE__;        \
432:       petscstack->currentsize++;                                        \
433:     }                                                                   \
435:   } while (0)

438:     if (strcmp(PETSC_FUNCTION_NAME,__FUNCT__) && strcmp(__FUNCT__,"User provided function")) { \
439:       (*PetscErrorPrintf)("%s%s:%d: __FUNCT__=\"%s\" does not agree with %s=\"%s\"\n",__SDIR__,__FILE__,__LINE__,__FUNCT__,PetscStringize(PETSC_FUNCTION_NAME),PETSC_FUNCTION_NAME); \
440:     }                                                                   \
441:   } while (0)

443: #define PetscStackPush(n) \
444:   do {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
445:     petscstack->function[petscstack->currentsize]  = n; \
446:     petscstack->file[petscstack->currentsize]      = "unknown"; \
447:     petscstack->directory[petscstack->currentsize] = "unknown"; \
448:     petscstack->line[petscstack->currentsize]      = 0; \
449:     petscstack->currentsize++; \
450:   } CHKMEMQ;} while (0)

452: #define PetscStackPop \
453:   do {CHKMEMQ; if (petscstack && petscstack->currentsize > 0) {        \
454:     petscstack->currentsize--; \
455:     petscstack->function[petscstack->currentsize]  = 0; \
456:     petscstack->file[petscstack->currentsize]      = 0; \
457:     petscstack->directory[petscstack->currentsize] = 0; \
458:     petscstack->line[petscstack->currentsize]      = 0; \
459:   }} while (0)

461: /*MC
462:    PetscFunctionReturn - Last executable line of each PETSc function
463:         used for error handling. Replaces return()

465:    Synopsis:
466:    void return(0);

468:    Not Collective

470:    Usage:
471: .vb
472:     ....
473:      return(0);
474:    }
475: .ve

477:    Notes:
478:      Not available in Fortran

480:    Level: developer


484: .keywords: traceback, error handling
485: M*/
486: #define PetscFunctionReturn(a) \
487:   do {\
488:   if (petscstack && petscstack->currentsize > 0) {        \
489:     petscstack->currentsize--; \
490:     petscstack->function[petscstack->currentsize]  = 0; \
491:     petscstack->file[petscstack->currentsize]      = 0; \
492:     petscstack->directory[petscstack->currentsize] = 0; \
493:     petscstack->line[petscstack->currentsize]      = 0; \
494:   }\
495:   return(a);} while (0)

497: #define PetscFunctionReturnVoid() \
498:   do {\
499:   if (petscstack && petscstack->currentsize > 0) {        \
500:     petscstack->currentsize--; \
501:     petscstack->function[petscstack->currentsize]  = 0; \
502:     petscstack->file[petscstack->currentsize]      = 0; \
503:     petscstack->directory[petscstack->currentsize] = 0; \
504:     petscstack->line[petscstack->currentsize]      = 0; \
505:   }\
506:   return;} while (0)

508: #else

511: #define PetscFunctionReturn(a)  return(a)
512: #define PetscFunctionReturnVoid() return
513: #define PetscStackPop     CHKMEMQ
514: #define PetscStackPush(f) CHKMEMQ
515: #define PetscStackActive        0

517: #endif

519: /*
520:     PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.

522:    Input Parameters:
523: +   name - string that gives the name of the function being called
524: -   routine - actual call to the routine

526:    Developer Note: this is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.

528: */
529: #define PetscStackCall(name,routine) PetscStackPush(name);routine;PetscStackPop;



539: #endif