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/src/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 61 #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */ 62 #define PETSC_ERR_FILE_READ 66 /* unable to read from file */ 63 #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */ 64 #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */ 65 66 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 67 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 68 69 #if defined(PETSC_USE_ERRORCHECKING) 70 71 /*MC 72 SETERRQ - Macro that is called when an error has been detected, 73 74 Not Collective 75 76 Synopsis: 77 void SETERRQ(PetscErrorCode errorcode,char *message) 78 79 80 Input Parameters: 81 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 82 - message - error message 83 84 Level: beginner 85 86 Notes: 87 Once the error handler is called the calling function is then returned from with the given error code. 88 89 See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments 90 91 92 Experienced users can set the error handler with PetscPushErrorHandler(). 93 94 Concepts: error^setting condition 95 96 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3() 97 M*/ 98 #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);} 99 100 /*MC 101 SETERRQ1 - Macro that is called when an error has been detected, 102 103 Not Collective 104 105 Synopsis: 106 void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg) 107 108 109 Input Parameters: 110 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 111 . message - error message in the printf format 112 - arg - argument (for example an integer, string or double) 113 114 Level: beginner 115 116 Notes: 117 Once the error handler is called the calling function is then returned from with the given error code. 118 119 Experienced users can set the error handler with PetscPushErrorHandler(). 120 121 Concepts: error^setting condition 122 123 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3() 124 M*/ 125 #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);} 126 127 /*MC 128 SETERRQ2 - Macro that is called when an error has been detected, 129 130 Not Collective 131 132 Synopsis: 133 void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2) 134 135 136 Input Parameters: 137 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 138 . message - error message in the printf format 139 . arg1 - argument (for example an integer, string or double) 140 - arg2 - argument (for example an integer, string or double) 141 142 Level: beginner 143 144 Notes: 145 Once the error handler is called the calling function is then returned from with the given error code. 146 147 Experienced users can set the error handler with PetscPushErrorHandler(). 148 149 Concepts: error^setting condition 150 151 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3() 152 M*/ 153 #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);} 154 155 /*MC 156 SETERRQ3 - Macro that is called when an error has been detected, 157 158 Not Collective 159 160 Synopsis: 161 void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 162 163 164 Input Parameters: 165 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 166 . message - error message in the printf format 167 . arg1 - argument (for example an integer, string or double) 168 . arg2 - argument (for example an integer, string or double) 169 - arg3 - argument (for example an integer, string or double) 170 171 Level: beginner 172 173 Notes: 174 Once the error handler is called the calling function is then returned from with the given error code. 175 176 Experienced users can set the error handler with PetscPushErrorHandler(). 177 178 Concepts: error^setting condition 179 180 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 181 M*/ 182 #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);} 183 184 #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);} 185 #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);} 186 #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);} 187 #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);} 188 #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);} 189 190 /*MC 191 CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns 192 193 Not Collective 194 195 Synopsis: 196 void CHKERRQ(PetscErrorCode errorcode) 197 198 199 Input Parameters: 200 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 201 202 Level: beginner 203 204 Notes: 205 Once the error handler is called the calling function is then returned from with the given error code. 206 207 Experienced users can set the error handler with PetscPushErrorHandler(). 208 209 CHKERRQ(n) is fundamentally a macro replacement for 210 if (n) return(PetscError(...,n,...)); 211 212 Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is 213 highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular, 214 it cannot be used in functions which return(void) or any other datatype. In these types of functions, 215 a more appropriate construct for using PETSc Error Handling would be 216 if (n) {PetscError(....); return(YourReturnType);} 217 218 Concepts: error^setting condition 219 220 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 221 M*/ 222 #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 223 224 #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);} 225 #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 226 227 /*MC 228 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 229 230 Not Collective 231 232 Synopsis: 233 CHKMEMQ; 234 235 Level: beginner 236 237 Notes: 238 Must run with the option -malloc_debug to enable this option 239 240 Once the error handler is called the calling function is then returned from with the given error code. 241 242 By defaults prints location where memory that is corrupted was allocated. 243 244 Concepts: memory corruption 245 246 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 247 PetscMallocValidate() 248 M*/ 249 #define CHKMEMQ {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} 250 251 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 252 extern PetscErrorCode __gierr; 253 #define _ __gierr = 254 #define ___ CHKERRQ(__gierr); 255 #endif 256 257 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode); 258 EXTERN void PETSC_DLLEXPORT PetscExceptionPop(); 259 260 /*MC 261 PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception, 262 rather than an error. That is if that error code is treated the program returns to this level, 263 but does not call the error handlers 264 265 Not Collective 266 267 Synopsis: 268 PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode); 269 270 Level: advanced 271 272 Notes: 273 PETSc must not be configured using the option --with-errorchecking=0 for this to work 274 275 276 Concepts: exceptions, exception hanlding 277 278 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 279 CHKERRQ() 280 M*/ 281 extern PetscErrorCode PetscExceptionTmp; 282 #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(),PetscExceptionTmp) 283 284 #else 285 #define SETERRQ(n,s) ; 286 #define SETERRQ1(n,s,a1) ; 287 #define SETERRQ2(n,s,a1,a2) ; 288 #define SETERRQ3(n,s,a1,a2,a3) ; 289 #define SETERRQ4(n,s,a1,a2,a3,a4) ; 290 #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ; 291 #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ; 292 #define SETERRABORT(comm,n,s) ; 293 294 #define CHKERRQ(n) ; 295 #define CHKERRABORT(comm,n) ; 296 #define CHKERRCONTINUE(n) ; 297 298 #define CHKMEMQ ; 299 300 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 301 #define _ 302 #define ___ 303 #endif 304 305 #define PetscExceptionTry1(a,b) a 306 #endif 307 308 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void); 309 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **); 310 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 311 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 312 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 313 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 314 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 315 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*); 316 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8); 317 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*); 318 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void); 319 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*); 320 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 321 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void); 322 323 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 324 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSetFPTrap(PetscFPTrap); 325 326 /* 327 Allows the code to build a stack frame as it runs 328 */ 329 #if defined(PETSC_USE_DEBUG) 330 331 #define PETSCSTACKSIZE 15 332 333 typedef struct { 334 const char *function[PETSCSTACKSIZE]; 335 const char *file[PETSCSTACKSIZE]; 336 const char *directory[PETSCSTACKSIZE]; 337 int line[PETSCSTACKSIZE]; 338 int currentsize; 339 } PetscStack; 340 341 extern PETSC_DLLEXPORT PetscStack *petscstack; 342 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCopy(PetscStack*,PetscStack*); 343 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPrint(PetscStack*,FILE* fp); 344 345 #define PetscStackActive (petscstack != 0) 346 347 348 /*MC 349 PetscFunctionBegin - First executable line of each PETSc function 350 used for error handling. 351 352 Synopsis: 353 void PetscFunctionBegin; 354 355 Usage: 356 .vb 357 int something; 358 359 PetscFunctionBegin; 360 .ve 361 362 Notes: 363 Not available in Fortran 364 365 Level: developer 366 367 .seealso: PetscFunctionReturn() 368 369 .keywords: traceback, error handling 370 M*/ 371 #define PetscFunctionBegin \ 372 {\ 373 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 374 petscstack->function[petscstack->currentsize] = __FUNCT__; \ 375 petscstack->file[petscstack->currentsize] = __FILE__; \ 376 petscstack->directory[petscstack->currentsize] = __SDIR__; \ 377 petscstack->line[petscstack->currentsize] = __LINE__; \ 378 petscstack->currentsize++; \ 379 }} 380 381 #define PetscStackPush(n) \ 382 {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 383 petscstack->function[petscstack->currentsize] = n; \ 384 petscstack->file[petscstack->currentsize] = "unknown"; \ 385 petscstack->directory[petscstack->currentsize] = "unknown"; \ 386 petscstack->line[petscstack->currentsize] = 0; \ 387 petscstack->currentsize++; \ 388 }} 389 390 #define PetscStackPop \ 391 {if (petscstack && petscstack->currentsize > 0) { \ 392 petscstack->currentsize--; \ 393 petscstack->function[petscstack->currentsize] = 0; \ 394 petscstack->file[petscstack->currentsize] = 0; \ 395 petscstack->directory[petscstack->currentsize] = 0; \ 396 petscstack->line[petscstack->currentsize] = 0; \ 397 }}; 398 399 /*MC 400 PetscFunctionReturn - Last executable line of each PETSc function 401 used for error handling. Replaces return() 402 403 Synopsis: 404 void PetscFunctionReturn(0); 405 406 Usage: 407 .vb 408 .... 409 PetscFunctionReturn(0); 410 } 411 .ve 412 413 Notes: 414 Not available in Fortran 415 416 Level: developer 417 418 .seealso: PetscFunctionBegin() 419 420 .keywords: traceback, error handling 421 M*/ 422 #define PetscFunctionReturn(a) \ 423 {\ 424 PetscStackPop; \ 425 return(a);} 426 427 #define PetscFunctionReturnVoid() \ 428 {\ 429 PetscStackPop; \ 430 return;} 431 432 433 #else 434 435 #define PetscFunctionBegin 436 #define PetscFunctionReturn(a) return(a) 437 #define PetscFunctionReturnVoid() return 438 #define PetscStackPop 439 #define PetscStackPush(f) 440 #define PetscStackActive 0 441 442 #endif 443 444 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCreate(void); 445 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackView(PetscViewer); 446 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDestroy(void); 447 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPublish(void); 448 EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDepublish(void); 449 450 451 PETSC_EXTERN_CXX_END 452 #endif 453