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