1 /* 2 Contains all error handling code for PETSc. 3 */ 4 #if !defined(__PETSCERROR_H) 5 #define __PETSCERROR_H 6 #include "petsc.h" 7 PETSC_EXTERN_CXX_BEGIN 8 9 /* 10 Defines the directory where the compiled source is located; used 11 in printing error messages. Each makefile has an entry 12 LOCDIR = thedirectory 13 and bmake/common_variables includes in CCPPFLAGS -D__SDIR__='"${LOCDIR}"' 14 which is a flag passed to the C/C++ compilers. 15 */ 16 #if !defined(__SDIR__) 17 #define __SDIR__ "unknowndirectory/" 18 #endif 19 20 /* 21 Defines the function where the compiled source is located; used 22 in printing error messages. 23 */ 24 #if !defined(__FUNCT__) 25 #define __FUNCT__ "User provided function" 26 #endif 27 28 /* 29 These are the generic error codes. These error codes are used 30 many different places in the PETSc source code. The string versions are 31 at src/sys/error/err.c any changes here must also be made there 32 33 */ 34 #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */ 35 #define PETSC_ERR_MEM_MALLOC_0 85 /* cannot malloc zero size */ 36 #define PETSC_ERR_SUP 56 /* no support for requested operation */ 37 #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */ 38 #define PETSC_ERR_ORDER 58 /* operation done in wrong order */ 39 #define PETSC_ERR_SIG 59 /* signal received */ 40 #define PETSC_ERR_FP 72 /* floating point exception */ 41 #define PETSC_ERR_COR 74 /* corrupted PETSc object */ 42 #define PETSC_ERR_LIB 76 /* error in library called by PETSc */ 43 #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */ 44 #define PETSC_ERR_MEMC 78 /* memory corruption */ 45 #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */ 46 #define PETSC_ERR_USER 83 /* user has not provided needed function */ 47 48 #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */ 49 #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */ 50 #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */ 51 #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */ 52 #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */ 53 #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */ 54 #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */ 55 #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */ 56 #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */ 57 #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */ 58 #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */ 59 #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */ 60 #define PETSC_ERR_ARG_DOMAIN 87 /* argument is not in domain of function */ 61 62 #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */ 63 #define PETSC_ERR_FILE_READ 66 /* unable to read from file */ 64 #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */ 65 #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */ 66 67 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 68 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 69 70 #if defined(PETSC_USE_ERRORCHECKING) 71 72 /*MC 73 SETERRQ - Macro that is called when an error has been detected, 74 75 Not Collective 76 77 Synopsis: 78 void SETERRQ(PetscErrorCode errorcode,char *message) 79 80 81 Input Parameters: 82 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 83 - message - error message 84 85 Level: beginner 86 87 Notes: 88 Once the error handler is called the calling function is then returned from with the given error code. 89 90 See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments 91 92 93 Experienced users can set the error handler with PetscPushErrorHandler(). 94 95 Concepts: error^setting condition 96 97 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3() 98 M*/ 99 #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);} 100 101 /*MC 102 SETERRQ1 - Macro that is called when an error has been detected, 103 104 Not Collective 105 106 Synopsis: 107 void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg) 108 109 110 Input Parameters: 111 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 112 . message - error message in the printf format 113 - arg - argument (for example an integer, string or double) 114 115 Level: beginner 116 117 Notes: 118 Once the error handler is called the calling function is then returned from with the given error code. 119 120 Experienced users can set the error handler with PetscPushErrorHandler(). 121 122 Concepts: error^setting condition 123 124 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3() 125 M*/ 126 #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);} 127 128 /*MC 129 SETERRQ2 - Macro that is called when an error has been detected, 130 131 Not Collective 132 133 Synopsis: 134 void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2) 135 136 137 Input Parameters: 138 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 139 . message - error message in the printf format 140 . arg1 - argument (for example an integer, string or double) 141 - arg2 - argument (for example an integer, string or double) 142 143 Level: beginner 144 145 Notes: 146 Once the error handler is called the calling function is then returned from with the given error code. 147 148 Experienced users can set the error handler with PetscPushErrorHandler(). 149 150 Concepts: error^setting condition 151 152 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3() 153 M*/ 154 #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);} 155 156 /*MC 157 SETERRQ3 - Macro that is called when an error has been detected, 158 159 Not Collective 160 161 Synopsis: 162 void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 163 164 165 Input Parameters: 166 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 167 . message - error message in the printf format 168 . arg1 - argument (for example an integer, string or double) 169 . arg2 - argument (for example an integer, string or double) 170 - arg3 - argument (for example an integer, string or double) 171 172 Level: beginner 173 174 Notes: 175 Once the error handler is called the calling function is then returned from with the given error code. 176 177 Experienced users can set the error handler with PetscPushErrorHandler(). 178 179 Concepts: error^setting condition 180 181 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 182 M*/ 183 #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);} 184 185 #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);} 186 #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);} 187 #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6);} 188 #define SETERRQ7(n,s,a1,a2,a3,a4,a5,a6,a7) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6,a7);} 189 #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);} 190 191 /*MC 192 CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns 193 194 Not Collective 195 196 Synopsis: 197 void CHKERRQ(PetscErrorCode errorcode) 198 199 200 Input Parameters: 201 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 202 203 Level: beginner 204 205 Notes: 206 Once the error handler is called the calling function is then returned from with the given error code. 207 208 Experienced users can set the error handler with PetscPushErrorHandler(). 209 210 CHKERRQ(n) is fundamentally a macro replacement for 211 if (n) return(PetscError(...,n,...)); 212 213 Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is 214 highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular, 215 it cannot be used in functions which return(void) or any other datatype. In these types of functions, 216 a more appropriate construct for using PETSc Error Handling would be 217 if (n) {PetscError(....); return(YourReturnType);} 218 219 Concepts: error^setting condition 220 221 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 222 M*/ 223 #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 224 225 #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);} 226 #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 227 228 /*MC 229 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 230 231 Not Collective 232 233 Synopsis: 234 CHKMEMQ; 235 236 Level: beginner 237 238 Notes: 239 Must run with the option -malloc_debug to enable this option 240 241 Once the error handler is called the calling function is then returned from with the given error code. 242 243 By defaults prints location where memory that is corrupted was allocated. 244 245 Concepts: memory corruption 246 247 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 248 PetscMallocValidate() 249 M*/ 250 #define CHKMEMQ {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} 251 252 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 253 extern PetscErrorCode __gierr; 254 #define _ __gierr = 255 #define ___ CHKERRQ(__gierr); 256 #endif 257 258 #define PETSC_EXCEPTIONS_MAX 256 259 extern PetscErrorCode PetscErrorUncatchable[PETSC_EXCEPTIONS_MAX]; 260 extern PetscInt PetscErrorUncatchableCount; 261 extern PetscErrorCode PetscExceptions[PETSC_EXCEPTIONS_MAX]; 262 extern PetscInt PetscExceptionsCount; 263 264 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode); 265 EXTERN void PETSC_DLLEXPORT PetscExceptionPop(PetscErrorCode); 266 267 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorSetCatchable(PetscErrorCode,PetscTruth); 268 269 /*MC 270 PetscExceptionCaught - Indicates if exception zierr was caught. 271 272 Not Collective 273 274 Synopsis: 275 PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr); 276 277 Input Parameters: 278 + xierr - error code returned from PetscExceptionTry1() 279 - zierr - error code you want it to be 280 281 Level: advanced 282 283 Notes: 284 PETSc must not be configured using the option --with-errorchecking=0 for this to work 285 286 Concepts: exceptions, exception hanlding 287 288 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 289 CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue() 290 M*/ 291 PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) { 292 PetscInt i; 293 if (xierr != zierr) return PETSC_FALSE; 294 for (i=0; i<PetscErrorUncatchableCount; i++) { 295 if (PetscErrorUncatchable[i] == zierr) { 296 return PETSC_FALSE; 297 } 298 } 299 return PETSC_TRUE; 300 } 301 302 /*MC 303 PetscExceptionValue - Indicates if the error code is one that is currently being tried 304 305 Not Collective 306 307 Synopsis: 308 PetscTruth PetscExceptionValue(PetscErrorCode xierr); 309 310 Input Parameters: 311 . xierr - error code 312 313 Level: developer 314 315 Notes: 316 PETSc must not be configured using the option --with-errorchecking=0 for this to work 317 318 Concepts: exceptions, exception hanlding 319 320 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 321 CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught() 322 M*/ 323 PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) { 324 PetscInt i; 325 for (i=0; i<PetscExceptionsCount; i++) { 326 if (PetscExceptions[i] == zierr) { 327 return PETSC_TRUE; 328 } 329 } 330 return PETSC_FALSE; 331 } 332 333 /*MC 334 PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception, 335 rather than an error. That is if that error code is treated the program returns to this level, 336 but does not call the error handlers 337 338 Not Collective 339 340 Synopsis: 341 PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode); 342 343 Level: advanced 344 345 Notes: 346 PETSc must not be configured using the option --with-errorchecking=0 for this to work 347 348 Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in 349 PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example 350 of how the local try is ignored if a higher (in the stack) one is also in effect. 351 352 Concepts: exceptions, exception hanlding 353 354 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 355 CHKERRQ(), PetscExceptionCaught() 356 M*/ 357 extern PetscErrorCode PetscExceptionTmp; 358 #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp) 359 360 #else 361 #define SETERRQ(n,s) ; 362 #define SETERRQ1(n,s,a1) ; 363 #define SETERRQ2(n,s,a1,a2) ; 364 #define SETERRQ3(n,s,a1,a2,a3) ; 365 #define SETERRQ4(n,s,a1,a2,a3,a4) ; 366 #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ; 367 #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ; 368 #define SETERRABORT(comm,n,s) ; 369 370 #define CHKERRQ(n) ; 371 #define CHKERRABORT(comm,n) ; 372 #define CHKERRCONTINUE(n) ; 373 374 #define CHKMEMQ ; 375 376 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 377 #define _ 378 #define ___ 379 #endif 380 381 #define PetscErrorSetCatchable(a,b) 0 382 #define PetscExceptionCaught(a,b) PETSC_FALSE 383 #define PetscExceptionValue(a) PETSC_FALSE 384 #define PetscExceptionTry1(a,b) a 385 #endif 386 387 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void); 388 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **); 389 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 390 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 391 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 392 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 393 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 394 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 395 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8); 396 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*); 397 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void); 398 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*); 399 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 400 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void); 401 402 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 403 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSetFPTrap(PetscFPTrap); 404 405 /* 406 Allows the code to build a stack frame as it runs 407 */ 408 #if defined(PETSC_USE_DEBUG) 409 410 #define PETSCSTACKSIZE 15 411 412 typedef struct { 413 const char *function[PETSCSTACKSIZE]; 414 const char *file[PETSCSTACKSIZE]; 415 const char *directory[PETSCSTACKSIZE]; 416 int line[PETSCSTACKSIZE]; 417 int currentsize; 418 } PetscStack; 419 420 extern PETSC_DLLEXPORT PetscStack *petscstack; 421 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCopy(PetscStack*,PetscStack*); 422 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPrint(PetscStack*,FILE* fp); 423 424 #define PetscStackActive (petscstack != 0) 425 426 427 /*MC 428 PetscFunctionBegin - First executable line of each PETSc function 429 used for error handling. 430 431 Synopsis: 432 void PetscFunctionBegin; 433 434 Usage: 435 .vb 436 int something; 437 438 PetscFunctionBegin; 439 .ve 440 441 Notes: 442 Not available in Fortran 443 444 Level: developer 445 446 .seealso: PetscFunctionReturn() 447 448 .keywords: traceback, error handling 449 M*/ 450 #define PetscFunctionBegin \ 451 {\ 452 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 453 petscstack->function[petscstack->currentsize] = __FUNCT__; \ 454 petscstack->file[petscstack->currentsize] = __FILE__; \ 455 petscstack->directory[petscstack->currentsize] = __SDIR__; \ 456 petscstack->line[petscstack->currentsize] = __LINE__; \ 457 petscstack->currentsize++; \ 458 }} 459 460 #define PetscStackPush(n) \ 461 {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 462 petscstack->function[petscstack->currentsize] = n; \ 463 petscstack->file[petscstack->currentsize] = "unknown"; \ 464 petscstack->directory[petscstack->currentsize] = "unknown"; \ 465 petscstack->line[petscstack->currentsize] = 0; \ 466 petscstack->currentsize++; \ 467 }} 468 469 #define PetscStackPop \ 470 {if (petscstack && petscstack->currentsize > 0) { \ 471 petscstack->currentsize--; \ 472 petscstack->function[petscstack->currentsize] = 0; \ 473 petscstack->file[petscstack->currentsize] = 0; \ 474 petscstack->directory[petscstack->currentsize] = 0; \ 475 petscstack->line[petscstack->currentsize] = 0; \ 476 }}; 477 478 /*MC 479 PetscFunctionReturn - Last executable line of each PETSc function 480 used for error handling. Replaces return() 481 482 Synopsis: 483 void PetscFunctionReturn(0); 484 485 Usage: 486 .vb 487 .... 488 PetscFunctionReturn(0); 489 } 490 .ve 491 492 Notes: 493 Not available in Fortran 494 495 Level: developer 496 497 .seealso: PetscFunctionBegin() 498 499 .keywords: traceback, error handling 500 M*/ 501 #define PetscFunctionReturn(a) \ 502 {\ 503 PetscStackPop; \ 504 return(a);} 505 506 #define PetscFunctionReturnVoid() \ 507 {\ 508 PetscStackPop; \ 509 return;} 510 511 512 #else 513 514 #define PetscFunctionBegin 515 #define PetscFunctionReturn(a) return(a) 516 #define PetscFunctionReturnVoid() return 517 #define PetscStackPop 518 #define PetscStackPush(f) 519 #define PetscStackActive 0 520 521 #endif 522 523 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCreate(void); 524 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackView(PetscViewer); 525 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDestroy(void); 526 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPublish(void); 527 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDepublish(void); 528 529 530 PETSC_EXTERN_CXX_END 531 #endif 532