1 /* $Id: petscerror.h,v 1.59 2001/09/07 20:13:16 bsmith Exp $ */ 2 /* 3 Contains all error handling code for PETSc. 4 */ 5 #if !defined(__PETSCERROR_H) 6 #define __PETSCERROR_H 7 #include "petsc.h" 8 PETSC_EXTERN_CXX_BEGIN 9 10 #if defined(PETSC_HAVE_AMS) 11 #include "ams.h" 12 #endif 13 14 /* 15 Defines the directory where the compiled source is located; used 16 in printing error messages. Each makefile has an entry 17 LOCDIR = thedirectory 18 and bmake/common_variables includes in CCPPFLAGS -D__SDIR__='"${LOCDIR}"' 19 which is a flag passed to the C/C++ compilers. 20 */ 21 #if !defined(__SDIR__) 22 #define __SDIR__ "unknowndirectory/" 23 #endif 24 25 /* 26 Defines the function where the compiled source is located; used 27 in printing error messages. 28 */ 29 #if !defined(__FUNCT__) 30 #define __FUNCT__ "User provided function" 31 #endif 32 33 /* 34 These are the generic error codes. These error codes are used 35 many different places in the PETSc source code. 36 37 */ 38 #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */ 39 #define PETSC_ERR_MEM_MALLOC_0 85 /* cannot malloc zero size */ 40 #define PETSC_ERR_SUP 56 /* no support for requested operation */ 41 #define PETSC_ERR_SIG 59 /* signal received */ 42 #define PETSC_ERR_FP 72 /* floating point exception */ 43 #define PETSC_ERR_COR 74 /* corrupted PETSc object */ 44 #define PETSC_ERR_LIB 76 /* error in library called by PETSc */ 45 #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */ 46 #define PETSC_ERR_MEMC 78 /* memory corruption */ 47 #define PETSC_ERR_MAX_ITER 82 /* Maximum iterations reached */ 48 49 #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */ 50 #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */ 51 #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */ 52 #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */ 53 #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */ 54 #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */ 55 #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */ 56 #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */ 57 #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */ 58 #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */ 59 #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */ 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_KSP_BRKDWN 70 /* break down in a Krylov method */ 67 68 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 69 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 70 71 #define PETSC_ERR_MESH_NULL_ELEM 84 /* Element had no interior */ 72 73 #define PETSC_ERR_DISC_SING_JAC 83 /* Singular element Jacobian */ 74 75 #if defined(PETSC_USE_DEBUG) 76 77 /*MC 78 SETERRQ - Macro that is called when an error has been detected, 79 80 Not Collective 81 82 Synopsis: 83 void SETERRQ(int errorcode,char *message) 84 85 86 Input Parameters: 87 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 88 - message - error message 89 90 Level: beginner 91 92 Notes: 93 Once the error handler is called the calling function is then returned from with the given error code. 94 95 See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments 96 97 98 Experienced users can set the error handler with PetscPushErrorHandler(). 99 100 Concepts: error^setting condition 101 102 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3() 103 M*/ 104 #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);} 105 106 /*MC 107 SETERRQ1 - Macro that is called when an error has been detected, 108 109 Not Collective 110 111 Synopsis: 112 void SETERRQ1(int errorcode,char *formatmessage,arg) 113 114 115 Input Parameters: 116 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 117 . message - error message in the printf format 118 - arg - argument (for example an integer, string or double) 119 120 Level: beginner 121 122 Notes: 123 Once the error handler is called the calling function is then returned from with the given error code. 124 125 Experienced users can set the error handler with PetscPushErrorHandler(). 126 127 Concepts: error^setting condition 128 129 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3() 130 M*/ 131 #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);} 132 133 /*MC 134 SETERRQ2 - Macro that is called when an error has been detected, 135 136 Not Collective 137 138 Synopsis: 139 void SETERRQ2(int errorcode,char *formatmessage,arg1,arg2) 140 141 142 Input Parameters: 143 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 144 . message - error message in the printf format 145 . arg1 - argument (for example an integer, string or double) 146 - arg2 - argument (for example an integer, string or double) 147 148 Level: beginner 149 150 Notes: 151 Once the error handler is called the calling function is then returned from with the given error code. 152 153 Experienced users can set the error handler with PetscPushErrorHandler(). 154 155 Concepts: error^setting condition 156 157 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3() 158 M*/ 159 #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);} 160 161 /*MC 162 SETERRQ3 - Macro that is called when an error has been detected, 163 164 Not Collective 165 166 Synopsis: 167 void SETERRQ3(int errorcode,char *formatmessage,arg1,arg2,arg3) 168 169 170 Input Parameters: 171 + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 172 . message - error message in the printf format 173 . arg1 - argument (for example an integer, string or double) 174 . arg2 - argument (for example an integer, string or double) 175 - arg3 - argument (for example an integer, string or double) 176 177 Level: beginner 178 179 Notes: 180 Once the error handler is called the calling function is then returned from with the given error code. 181 182 Experienced users can set the error handler with PetscPushErrorHandler(). 183 184 Concepts: error^setting condition 185 186 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 187 M*/ 188 #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);} 189 190 #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);} 191 #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);} 192 #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);} 193 #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);} 194 #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);} 195 196 /*MC 197 CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns 198 199 Not Collective 200 201 Synopsis: 202 void CHKERRQ(int errorcode) 203 204 205 Input Parameters: 206 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 207 208 Level: beginner 209 210 Notes: 211 Once the error handler is called the calling function is then returned from with the given error code. 212 213 Experienced users can set the error handler with PetscPushErrorHandler(). 214 215 Concepts: error^setting condition 216 217 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 218 M*/ 219 #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 220 221 #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);} 222 #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");} 223 224 /*MC 225 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 226 227 Not Collective 228 229 Synopsis: 230 CHKMEMQ; 231 232 Level: beginner 233 234 Notes: 235 Must run with the option -trdebug to enable this option 236 237 Once the error handler is called the calling function is then returned from with the given error code. 238 239 By defaults prints location where memory that is corrupted was allocated. 240 241 Concepts: memory corruption 242 243 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(), 244 PetscTrValid() 245 M*/ 246 #define CHKMEMQ {int _7_ierr = PetscTrValid(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} 247 248 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 249 extern int __gierr; 250 #define _ __gierr = 251 #define ___ CHKERRQ(__gierr); 252 #endif 253 254 #else 255 #define SETERRQ(n,s) ; 256 #define SETERRQ1(n,s,a1) ; 257 #define SETERRQ2(n,s,a1,a2) ; 258 #define SETERRQ3(n,s,a1,a2,a3) ; 259 #define SETERRQ4(n,s,a1,a2,a3,a4) ; 260 #define SETERRABORT(comm,n,s) ; 261 262 #define CHKERRQ(n) ; 263 #define CHKERRABORT(comm,n) ; 264 #define CHKERRCONTINUE(n) ; 265 266 #define CHKMEMQ ; 267 268 #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR) 269 #define _ 270 #define ___ 271 #endif 272 273 #endif 274 275 EXTERN int PetscErrorMessage(int,const char*[],char **); 276 EXTERN int PetscTraceBackErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 277 EXTERN int PetscIgnoreErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 278 EXTERN int PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 279 EXTERN int PetscStopErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 280 EXTERN int PetscAbortErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 281 EXTERN int PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*); 282 EXTERN int PetscError(int,const char*,const char*,const char*,int,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8); 283 EXTERN int PetscPushErrorHandler(int (*handler)(int,const char*,const char*,const char*,int,int,const char*,void*),void*); 284 EXTERN int PetscPopErrorHandler(void); 285 EXTERN int PetscDefaultSignalHandler(int,void*); 286 EXTERN int PetscPushSignalHandler(int (*)(int,void *),void*); 287 EXTERN int PetscPopSignalHandler(void); 288 289 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 290 EXTERN int PetscSetFPTrap(PetscFPTrap); 291 292 /* 293 Allows the code to build a stack frame as it runs 294 */ 295 #if defined(PETSC_USE_STACK) 296 297 #define PETSCSTACKSIZE 15 298 299 typedef struct { 300 const char *function[PETSCSTACKSIZE]; 301 const char *file[PETSCSTACKSIZE]; 302 const char *directory[PETSCSTACKSIZE]; 303 int line[PETSCSTACKSIZE]; 304 int currentsize; 305 } PetscStack; 306 307 extern PetscStack *petscstack; 308 EXTERN int PetscStackCopy(PetscStack*,PetscStack*); 309 EXTERN int PetscStackPrint(PetscStack*,FILE* fp); 310 311 #define PetscStackActive (petscstack != 0) 312 313 #if !defined(PETSC_HAVE_AMS) 314 315 /*MC 316 PetscFunctionBegin - First executable line of each PETSc function 317 used for error handling. 318 319 Synopsis: 320 void PetscFunctionBegin; 321 322 Usage: 323 .vb 324 int something; 325 326 PetscFunctionBegin; 327 .ve 328 329 Notes: 330 Not available in Fortran 331 332 Level: developer 333 334 .seealso: PetscFunctionReturn() 335 336 .keywords: traceback, error handling 337 M*/ 338 #define PetscFunctionBegin \ 339 {\ 340 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 341 petscstack->function[petscstack->currentsize] = __FUNCT__; \ 342 petscstack->file[petscstack->currentsize] = __FILE__; \ 343 petscstack->directory[petscstack->currentsize] = __SDIR__; \ 344 petscstack->line[petscstack->currentsize] = __LINE__; \ 345 petscstack->currentsize++; \ 346 }} 347 348 #define PetscStackPush(n) \ 349 {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 350 petscstack->function[petscstack->currentsize] = n; \ 351 petscstack->file[petscstack->currentsize] = "unknown"; \ 352 petscstack->directory[petscstack->currentsize] = "unknown"; \ 353 petscstack->line[petscstack->currentsize] = 0; \ 354 petscstack->currentsize++; \ 355 }} 356 357 #define PetscStackPop \ 358 {if (petscstack && petscstack->currentsize > 0) { \ 359 petscstack->currentsize--; \ 360 petscstack->function[petscstack->currentsize] = 0; \ 361 petscstack->file[petscstack->currentsize] = 0; \ 362 petscstack->directory[petscstack->currentsize] = 0; \ 363 petscstack->line[petscstack->currentsize] = 0; \ 364 }}; 365 366 /*MC 367 PetscFunctionReturn - Last executable line of each PETSc function 368 used for error handling. Replaces return() 369 370 Synopsis: 371 void PetscFunctionReturn(0); 372 373 Usage: 374 .vb 375 .... 376 PetscFunctionReturn(0); 377 } 378 .ve 379 380 Notes: 381 Not available in Fortran 382 383 Level: developer 384 385 .seealso: PetscFunctionBegin() 386 387 .keywords: traceback, error handling 388 M*/ 389 #define PetscFunctionReturn(a) \ 390 {\ 391 PetscStackPop; \ 392 return(a);} 393 394 #define PetscFunctionReturnVoid() \ 395 {\ 396 PetscStackPop; \ 397 return;} 398 399 #else 400 401 /* 402 Duplicate Code for when the ALICE Memory Snooper (AMS) 403 is being used. When PETSC_HAVE_AMS is defined. 404 405 stack_mem is the AMS memory that contains fields for the 406 number of stack frames and names of the stack frames 407 */ 408 409 extern AMS_Memory stack_mem; 410 extern int stack_err; 411 412 #define PetscFunctionBegin \ 413 {\ 414 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 415 if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\ 416 petscstack->function[petscstack->currentsize] = __FUNCT__; \ 417 petscstack->file[petscstack->currentsize] = __FILE__; \ 418 petscstack->directory[petscstack->currentsize] = __SDIR__; \ 419 petscstack->line[petscstack->currentsize] = __LINE__; \ 420 petscstack->currentsize++; \ 421 if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\ 422 }} 423 424 #define PetscStackPush(n) \ 425 {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 426 if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\ 427 petscstack->function[petscstack->currentsize] = n; \ 428 petscstack->file[petscstack->currentsize] = "unknown"; \ 429 petscstack->directory[petscstack->currentsize] = "unknown"; \ 430 petscstack->line[petscstack->currentsize] = 0; \ 431 petscstack->currentsize++; \ 432 if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\ 433 }} 434 435 #define PetscStackPop \ 436 {if (petscstack && petscstack->currentsize > 0) { \ 437 if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\ 438 petscstack->currentsize--; \ 439 petscstack->function[petscstack->currentsize] = 0; \ 440 petscstack->file[petscstack->currentsize] = 0; \ 441 petscstack->directory[petscstack->currentsize] = 0; \ 442 petscstack->line[petscstack->currentsize] = 0; \ 443 if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\ 444 }}; 445 446 #define PetscFunctionReturn(a) \ 447 {\ 448 PetscStackPop; \ 449 return(a);} 450 451 #define PetscFunctionReturnVoid() \ 452 {\ 453 PetscStackPop; \ 454 return;} 455 456 457 #endif 458 459 #else 460 461 #define PetscFunctionBegin 462 #define PetscFunctionReturn(a) return(a) 463 #define PetscFunctionReturnVoid() return() 464 #define PetscStackPop 465 #define PetscStackPush(f) 466 #define PetscStackActive 0 467 468 #endif 469 470 EXTERN int PetscStackCreate(void); 471 EXTERN int PetscStackView(PetscViewer); 472 EXTERN int PetscStackDestroy(void); 473 EXTERN int PetscStackPublish(void); 474 EXTERN int PetscStackDepublish(void); 475 476 477 PETSC_EXTERN_CXX_END 478 #endif 479