1 /* 2 Contains all error handling interfaces for PETSc. 3 */ 4 #if !defined(__PETSCERROR_H) 5 #define __PETSCERROR_H 6 7 /* 8 Defines the function where the compiled source is located; used 9 in printing error messages. This is defined here in case the user 10 does not declare it. 11 */ 12 #if !defined(__FUNCT__) 13 #define __FUNCT__ "User provided function" 14 #endif 15 16 /* 17 These are the generic error codes. These error codes are used 18 many different places in the PETSc source code. The string versions are 19 at src/sys/error/err.c any changes here must also be made there 20 These are also define in include/petsc/finclude/petscerror.h any CHANGES here 21 must be also made there. 22 23 */ 24 #define PETSC_ERR_MIN_VALUE 54 /* should always be one less then the smallest value */ 25 26 #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */ 27 #define PETSC_ERR_SUP 56 /* no support for requested operation */ 28 #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */ 29 #define PETSC_ERR_ORDER 58 /* operation done in wrong order */ 30 #define PETSC_ERR_SIG 59 /* signal received */ 31 #define PETSC_ERR_FP 72 /* floating point exception */ 32 #define PETSC_ERR_COR 74 /* corrupted PETSc object */ 33 #define PETSC_ERR_LIB 76 /* error in library called by PETSc */ 34 #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */ 35 #define PETSC_ERR_MEMC 78 /* memory corruption */ 36 #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */ 37 #define PETSC_ERR_USER 83 /* user has not provided needed function */ 38 #define PETSC_ERR_SYS 88 /* error in system call */ 39 #define PETSC_ERR_POINTER 70 /* pointer does not point to valid address */ 40 41 #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */ 42 #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */ 43 #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */ 44 #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */ 45 #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */ 46 #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */ 47 #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */ 48 #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */ 49 #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */ 50 #define PETSC_ERR_ARG_TYPENOTSET 89 /* the type of the object has not yet been set */ 51 #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */ 52 #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */ 53 #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */ 54 55 #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */ 56 #define PETSC_ERR_FILE_READ 66 /* unable to read from file */ 57 #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */ 58 #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */ 59 60 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 61 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 62 63 #define PETSC_ERR_INT_OVERFLOW 84 64 65 #define PETSC_ERR_FLOP_COUNT 90 66 #define PETSC_ERR_NOT_CONVERGED 91 /* solver did not converge */ 67 #define PETSC_ERR_MISSING_FACTOR 92 /* MatGetFactor() failed */ 68 #define PETSC_ERR_MAX_VALUE 93 /* this is always the one more than the largest error code */ 69 70 #define PetscStringizeArg(a) #a 71 #define PetscStringize(a) PetscStringizeArg(a) 72 73 #if defined(PETSC_USE_ERRORCHECKING) 74 75 /*MC 76 SETERRQ - Macro to be called when an error has been detected, 77 78 Synopsis: 79 #include <petscsys.h> 80 PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode errorcode,char *message) 81 82 Not Collective 83 84 Input Parameters: 85 + comm - A communicator, so that the error can be collective 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 In Fortran MPI_Abort() is always called 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(comm,n,s) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s) 105 106 /*MC 107 SETERRQ1 - Macro that is called when an error has been detected, 108 109 Synopsis: 110 #include <petscsys.h> 111 PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg) 112 113 Not Collective 114 115 Input Parameters: 116 + comm - A communicator, so that the error can be collective 117 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 118 . message - error message in the printf format 119 - arg - argument (for example an integer, string or double) 120 121 Level: beginner 122 123 Notes: 124 Once the error handler is called the calling function is then returned from with the given error code. 125 126 Experienced users can set the error handler with PetscPushErrorHandler(). 127 128 Concepts: error^setting condition 129 130 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3() 131 M*/ 132 #define SETERRQ1(comm,n,s,a1) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1) 133 134 /*MC 135 SETERRQ2 - Macro that is called when an error has been detected, 136 137 Synopsis: 138 #include <petscsys.h> 139 PetscErrorCode SETERRQ2(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2) 140 141 Not Collective 142 143 Input Parameters: 144 + comm - A communicator, so that the error can be collective 145 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 146 . message - error message in the printf format 147 . arg1 - argument (for example an integer, string or double) 148 - arg2 - argument (for example an integer, string or double) 149 150 Level: beginner 151 152 Notes: 153 Once the error handler is called the calling function is then returned from with the given error code. 154 155 Experienced users can set the error handler with PetscPushErrorHandler(). 156 157 Concepts: error^setting condition 158 159 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3() 160 M*/ 161 #define SETERRQ2(comm,n,s,a1,a2) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2) 162 163 /*MC 164 SETERRQ3 - Macro that is called when an error has been detected, 165 166 Synopsis: 167 #include <petscsys.h> 168 PetscErrorCode SETERRQ3(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 169 170 Not Collective 171 172 Input Parameters: 173 + comm - A communicator, so that the error can be collective 174 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 175 . message - error message in the printf format 176 . arg1 - argument (for example an integer, string or double) 177 . arg2 - argument (for example an integer, string or double) 178 - arg3 - argument (for example an integer, string or double) 179 180 Level: beginner 181 182 Notes: 183 Once the error handler is called the calling function is then returned from with the given error code. 184 185 There are also versions for 4, 5, 6 and 7 arguments. 186 187 Experienced users can set the error handler with PetscPushErrorHandler(). 188 189 Concepts: error^setting condition 190 191 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 192 M*/ 193 #define SETERRQ3(comm,n,s,a1,a2,a3) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3) 194 195 /*MC 196 SETERRQ4 - Macro that is called when an error has been detected, 197 198 Synopsis: 199 #include <petscsys.h> 200 PetscErrorCode SETERRQ4(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 201 202 Not Collective 203 204 Input Parameters: 205 + comm - A communicator, so that the error can be collective 206 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 207 . message - error message in the printf format 208 . arg1 - argument (for example an integer, string or double) 209 . arg2 - argument (for example an integer, string or double) 210 . arg3 - argument (for example an integer, string or double) 211 - arg4 - argument (for example an integer, string or double) 212 213 Level: beginner 214 215 Notes: 216 Once the error handler is called the calling function is then returned from with the given error code. 217 218 There are also versions for 4, 5, 6 and 7 arguments. 219 220 Experienced users can set the error handler with PetscPushErrorHandler(). 221 222 Concepts: error^setting condition 223 224 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 225 M*/ 226 #define SETERRQ4(comm,n,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4) 227 228 /*MC 229 SETERRQ5 - Macro that is called when an error has been detected, 230 231 Synopsis: 232 #include <petscsys.h> 233 PetscErrorCode SETERRQ5(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 234 235 Not Collective 236 237 Input Parameters: 238 + comm - A communicator, so that the error can be collective 239 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 240 . message - error message in the printf format 241 . arg1 - argument (for example an integer, string or double) 242 . arg2 - argument (for example an integer, string or double) 243 . arg3 - argument (for example an integer, string or double) 244 . arg4 - argument (for example an integer, string or double) 245 - arg5 - argument (for example an integer, string or double) 246 247 Level: beginner 248 249 Notes: 250 Once the error handler is called the calling function is then returned from with the given error code. 251 252 There are also versions for 4, 5, 6 and 7 arguments. 253 254 Experienced users can set the error handler with PetscPushErrorHandler(). 255 256 Concepts: error^setting condition 257 258 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 259 M*/ 260 #define SETERRQ5(comm,n,s,a1,a2,a3,a4,a5) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5) 261 262 /*MC 263 SETERRQ6 - Macro that is called when an error has been detected, 264 265 Synopsis: 266 #include <petscsys.h> 267 PetscErrorCode SETERRQ6(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 268 269 Not Collective 270 271 Input Parameters: 272 + comm - A communicator, so that the error can be collective 273 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 274 . message - error message in the printf format 275 . arg1 - argument (for example an integer, string or double) 276 . arg2 - argument (for example an integer, string or double) 277 . arg3 - argument (for example an integer, string or double) 278 . arg4 - argument (for example an integer, string or double) 279 . arg5 - argument (for example an integer, string or double) 280 - arg6 - argument (for example an integer, string or double) 281 282 Level: beginner 283 284 Notes: 285 Once the error handler is called the calling function is then returned from with the given error code. 286 287 There are also versions for 4, 5, 6 and 7 arguments. 288 289 Experienced users can set the error handler with PetscPushErrorHandler(). 290 291 Concepts: error^setting condition 292 293 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 294 M*/ 295 #define SETERRQ6(comm,n,s,a1,a2,a3,a4,a5,a6) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6) 296 297 /*MC 298 SETERRQ7 - Macro that is called when an error has been detected, 299 300 Synopsis: 301 #include <petscsys.h> 302 PetscErrorCode SETERRQ7(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 303 304 Not Collective 305 306 Input Parameters: 307 + comm - A communicator, so that the error can be collective 308 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 309 . message - error message in the printf format 310 . arg1 - argument (for example an integer, string or double) 311 . arg2 - argument (for example an integer, string or double) 312 . arg3 - argument (for example an integer, string or double) 313 . arg4 - argument (for example an integer, string or double) 314 . arg5 - argument (for example an integer, string or double) 315 . arg6 - argument (for example an integer, string or double) 316 - arg7 - argument (for example an integer, string or double) 317 318 Level: beginner 319 320 Notes: 321 Once the error handler is called the calling function is then returned from with the given error code. 322 323 There are also versions for 4, 5, 6 and 7 arguments. 324 325 Experienced users can set the error handler with PetscPushErrorHandler(). 326 327 Concepts: error^setting condition 328 329 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 330 M*/ 331 #define SETERRQ7(comm,n,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7) 332 333 /*MC 334 SETERRQ8 - Macro that is called when an error has been detected, 335 336 Synopsis: 337 #include <petscsys.h> 338 PetscErrorCode SETERRQ8(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3) 339 340 Not Collective 341 342 Input Parameters: 343 + comm - A communicator, so that the error can be collective 344 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 345 . message - error message in the printf format 346 . arg1 - argument (for example an integer, string or double) 347 . arg2 - argument (for example an integer, string or double) 348 . arg3 - argument (for example an integer, string or double) 349 . arg4 - argument (for example an integer, string or double) 350 . arg5 - argument (for example an integer, string or double) 351 . arg6 - argument (for example an integer, string or double) 352 . arg7 - argument (for example an integer, string or double) 353 - arg8 - argument (for example an integer, string or double) 354 355 Level: beginner 356 357 Notes: 358 Once the error handler is called the calling function is then returned from with the given error code. 359 360 There are also versions for 4, 5, 6 and 7 arguments. 361 362 Experienced users can set the error handler with PetscPushErrorHandler(). 363 364 Concepts: error^setting condition 365 366 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 367 M*/ 368 #define SETERRQ8(comm,n,s,a1,a2,a3,a4,a5,a6,a7,a8) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8) 369 370 /*MC 371 SETERRABORT - Macro that can be called when an error has been detected, 372 373 Synopsis: 374 #include <petscsys.h> 375 PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode errorcode,char *message) 376 377 Not Collective 378 379 Input Parameters: 380 + comm - A communicator, so that the error can be collective 381 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 382 - message - error message in the printf format 383 384 Level: beginner 385 386 Notes: 387 This function just calls MPI_Abort(). 388 389 Concepts: error^setting condition 390 391 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 392 M*/ 393 #define SETERRABORT(comm,n,s) do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,n);} while (0) 394 395 /*MC 396 CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns 397 398 Synopsis: 399 #include <petscsys.h> 400 PetscErrorCode CHKERRQ(PetscErrorCode errorcode) 401 402 Not Collective 403 404 Input Parameters: 405 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 406 407 Level: beginner 408 409 Notes: 410 Once the error handler is called the calling function is then returned from with the given error code. 411 412 Experienced users can set the error handler with PetscPushErrorHandler(). 413 414 CHKERRQ(n) is fundamentally a macro replacement for 415 if (n) return(PetscError(...,n,...)); 416 417 Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is 418 highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular, 419 it cannot be used in functions which return(void) or any other datatype. In these types of functions, 420 you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or 421 if (n) {PetscError(....); return(YourReturnType);} 422 where you may pass back a NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have 423 MPI_Abort() returned immediately. 424 425 In Fortran MPI_Abort() is always called 426 427 Concepts: error^setting condition 428 429 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 430 M*/ 431 #define CHKERRQ(n) do {if (PetscUnlikely(n)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");} while (0) 432 433 #define CHKERRV(n) do {if (PetscUnlikely(n)) {n = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");return;}} while(0) 434 #define CHKERRABORT(comm,n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,n);}} while (0) 435 #define CHKERRCONTINUE(n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");}} while (0) 436 437 #ifdef PETSC_CLANGUAGE_CXX 438 439 /*MC 440 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception 441 442 Synopsis: 443 #include <petscsys.h> 444 void CHKERRXX(PetscErrorCode errorcode) 445 446 Not Collective 447 448 Input Parameters: 449 . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h 450 451 Level: beginner 452 453 Notes: 454 Once the error handler throws a ??? exception. 455 456 You can use CHKERRV() which returns without an error code (bad idea since the error is ignored) 457 or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately. 458 459 Concepts: error^setting condition 460 461 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ 462 M*/ 463 #define CHKERRXX(n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_IN_CXX,0);}} while(0) 464 465 #endif 466 467 /*MC 468 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 469 470 Synopsis: 471 #include <petscsys.h> 472 CHKMEMQ; 473 474 Not Collective 475 476 Level: beginner 477 478 Notes: 479 We highly recommend using valgrind http://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind for finding memory problems. This is useful 480 on systems that do not have valgrind, but much much less useful. 481 482 Must run with the option -malloc_debug to enable this option 483 484 Once the error handler is called the calling function is then returned from with the given error code. 485 486 By defaults prints location where memory that is corrupted was allocated. 487 488 Use CHKMEMA for functions that return void 489 490 Concepts: memory corruption 491 492 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 493 PetscMallocValidate() 494 M*/ 495 #define CHKMEMQ do {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while(0) 496 497 #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__) 498 499 #else /* PETSC_USE_ERRORCHECKING */ 500 501 /* 502 These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0 503 */ 504 505 #define SETERRQ(c,n,s) 506 #define SETERRQ1(c,n,s,a1) 507 #define SETERRQ2(c,n,s,a1,a2) 508 #define SETERRQ3(c,n,s,a1,a2,a3) 509 #define SETERRQ4(c,n,s,a1,a2,a3,a4) 510 #define SETERRQ5(c,n,s,a1,a2,a3,a4,a5) 511 #define SETERRQ6(c,n,s,a1,a2,a3,a4,a5,a6) 512 #define SETERRQ7(c,n,s,a1,a2,a3,a4,a5,a6,a7) 513 #define SETERRQ8(c,n,s,a1,a2,a3,a4,a5,a6,a7,a8) 514 #define SETERRABORT(comm,n,s) 515 516 #define CHKERRQ(n) ; 517 #define CHKERRABORT(comm,n) ; 518 #define CHKERRCONTINUE(n) ; 519 #define CHKMEMQ ; 520 521 #ifdef PETSC_CLANGUAGE_CXX 522 #define CHKERRXX(n) ; 523 #endif 524 525 #endif /* PETSC_USE_ERRORCHECKING */ 526 527 /*E 528 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 529 530 Level: advanced 531 532 PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated 533 534 Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 535 536 .seealso: PetscError(), SETERRXX() 537 E*/ 538 typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType; 539 540 #if defined(__clang_analyzer__) 541 __attribute__((analyzer_noreturn)) 542 #endif 543 PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...); 544 545 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 546 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **); 547 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 548 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 549 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 550 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 551 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 552 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 553 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 554 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*); 555 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 556 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*); 557 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 558 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 559 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 560 561 /*MC 562 PetscErrorPrintf - Prints error messages. 563 564 Synopsis: 565 #include <petscsys.h> 566 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 567 568 Not Collective 569 570 Input Parameters: 571 . format - the usual printf() format string 572 573 Options Database Keys: 574 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 575 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 576 577 Notes: Use 578 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 579 $ error is handled.) and 580 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 581 582 Use 583 PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file. 584 PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file. 585 586 Use 587 PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print 588 589 Level: developer 590 591 Fortran Note: 592 This routine is not supported in Fortran. 593 594 Concepts: error messages^printing 595 Concepts: printing^error messages 596 597 .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscErrorHandlerPush(), PetscVFPrintf(), PetscHelpPrintf() 598 M*/ 599 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...); 600 601 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 602 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 603 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 604 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 605 606 /* 607 Allows the code to build a stack frame as it runs 608 */ 609 610 #define PETSCSTACKSIZE 64 611 612 typedef struct { 613 const char *function[PETSCSTACKSIZE]; 614 const char *file[PETSCSTACKSIZE]; 615 int line[PETSCSTACKSIZE]; 616 PetscBool petscroutine[PETSCSTACKSIZE]; 617 int currentsize; 618 int hotdepth; 619 } PetscStack; 620 621 PETSC_EXTERN PetscStack *petscstack; 622 623 PetscErrorCode PetscStackCopy(PetscStack*,PetscStack*); 624 PetscErrorCode PetscStackPrint(PetscStack *,FILE*); 625 #if defined(PETSC_USE_DEBUG) 626 PETSC_STATIC_INLINE PetscBool PetscStackActive(void) 627 { 628 return(petscstack ? PETSC_TRUE : PETSC_FALSE); 629 } 630 631 /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error 632 * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at 633 * least more useful than "unknown" because it can distinguish multiple calls from the same function. 634 */ 635 636 #define PetscStackPushNoCheck(funct,petsc_routine,hot) \ 637 do { \ 638 PetscStackSAWsTakeAccess(); \ 639 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 640 petscstack->function[petscstack->currentsize] = funct; \ 641 petscstack->file[petscstack->currentsize] = __FILE__; \ 642 petscstack->line[petscstack->currentsize] = __LINE__; \ 643 petscstack->petscroutine[petscstack->currentsize] = petsc_routine; \ 644 petscstack->currentsize++; \ 645 } \ 646 if (petscstack) { \ 647 petscstack->hotdepth += (hot || petscstack->hotdepth); \ 648 } \ 649 PetscStackSAWsGrantAccess(); \ 650 } while (0) 651 652 #define PetscStackPopNoCheck \ 653 do { \ 654 PetscStackSAWsTakeAccess(); \ 655 if (petscstack && petscstack->currentsize > 0) { \ 656 petscstack->currentsize--; \ 657 petscstack->function[petscstack->currentsize] = 0; \ 658 petscstack->file[petscstack->currentsize] = 0; \ 659 petscstack->line[petscstack->currentsize] = 0; \ 660 petscstack->petscroutine[petscstack->currentsize] = PETSC_FALSE;\ 661 } \ 662 if (petscstack) { \ 663 petscstack->hotdepth = PetscMax(petscstack->hotdepth-1,0); \ 664 } \ 665 PetscStackSAWsGrantAccess(); \ 666 } while (0) 667 668 /*MC 669 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 670 line of PETSc functions should be PetscFunctionReturn(0); 671 672 Synopsis: 673 #include <petscsys.h> 674 void PetscFunctionBegin; 675 676 Not Collective 677 678 Usage: 679 .vb 680 int something; 681 682 PetscFunctionBegin; 683 .ve 684 685 Notes: 686 Use PetscFunctionBeginUser for application codes. 687 688 Not available in Fortran 689 690 Level: developer 691 692 .seealso: PetscFunctionReturn(), PetscFunctionBeginHot(), PetscFunctionBeginUser() 693 694 .keywords: traceback, error handling 695 M*/ 696 #define PetscFunctionBegin do { \ 697 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_FALSE); \ 698 PetscCheck__FUNCT__(); \ 699 PetscRegister__FUNCT__(); \ 700 } while (0) 701 702 /*MC 703 PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in 704 performance-critical circumstances. Use of this function allows for lighter profiling by default. 705 706 Synopsis: 707 #include <petscsys.h> 708 void PetscFunctionBeginHot; 709 710 Not Collective 711 712 Usage: 713 .vb 714 int something; 715 716 PetscFunctionBeginHot; 717 .ve 718 719 Notes: 720 Not available in Fortran 721 722 Level: developer 723 724 .seealso: PetscFunctionBegin, PetscFunctionReturn() 725 726 .keywords: traceback, error handling 727 M*/ 728 #define PetscFunctionBeginHot do { \ 729 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_TRUE); \ 730 PetscCheck__FUNCT__(); \ 731 PetscRegister__FUNCT__(); \ 732 } while (0) 733 734 /*MC 735 PetscFunctionBeginUser - First executable line of user provided PETSc routine 736 737 Synopsis: 738 #include <petscsys.h> 739 void PetscFunctionBeginUser; 740 741 Not Collective 742 743 Usage: 744 .vb 745 int something; 746 747 PetscFunctionBegin; 748 .ve 749 750 Notes: 751 Final line of PETSc functions should be PetscFunctionReturn(0) except for main(). 752 753 Not available in Fortran 754 755 Level: intermediate 756 757 .seealso: PetscFunctionReturn(), PetscFunctionBegin, PetscFunctionBeginHot 758 759 .keywords: traceback, error handling 760 M*/ 761 #define PetscFunctionBeginUser \ 762 do { \ 763 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_FALSE,PETSC_FALSE); \ 764 PetscCheck__FUNCT__(); \ 765 PetscRegister__FUNCT__(); \ 766 } while (0) 767 768 769 #if defined(PETSC_SERIALIZE_FUNCTIONS) 770 #include <petsc/private/petscfptimpl.h> 771 /* 772 Registers the current function into the global function pointer to function name table 773 774 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 775 */ 776 #define PetscRegister__FUNCT__() do { \ 777 static PetscBool __chked = PETSC_FALSE; \ 778 if (!__chked) {\ 779 void *ptr; PetscDLSym(NULL,__FUNCT__,&ptr);\ 780 __chked = PETSC_TRUE;\ 781 }} while (0) 782 #else 783 #define PetscRegister__FUNCT__() 784 #endif 785 786 #define PetscCheck__FUNCT__() do { PetscBool _sc1,_sc2; \ 787 PetscStrcmpNoError(PETSC_FUNCTION_NAME,__FUNCT__,&_sc1);\ 788 PetscStrcmpNoError(__FUNCT__,"User provided function",&_sc2);\ 789 if (!_sc1 && !_sc2) { \ 790 printf("%s:%d: __FUNCT__=\"%s\" does not agree with %s=\"%s\"\n",__FILE__,__LINE__,__FUNCT__,PetscStringize(PETSC_FUNCTION_NAME),PETSC_FUNCTION_NAME); \ 791 } \ 792 } while (0) 793 794 #define PetscStackPush(n) \ 795 do { \ 796 PetscStackPushNoCheck(n,PETSC_FALSE,PETSC_FALSE); \ 797 CHKMEMQ; \ 798 } while (0) 799 800 #define PetscStackPop \ 801 do { \ 802 CHKMEMQ; \ 803 PetscStackPopNoCheck; \ 804 } while (0) 805 806 /*MC 807 PetscFunctionReturn - Last executable line of each PETSc function 808 used for error handling. Replaces return() 809 810 Synopsis: 811 #include <petscsys.h> 812 void PetscFunctionReturn(0); 813 814 Not Collective 815 816 Usage: 817 .vb 818 .... 819 PetscFunctionReturn(0); 820 } 821 .ve 822 823 Notes: 824 Not available in Fortran 825 826 Level: developer 827 828 .seealso: PetscFunctionBegin() 829 830 .keywords: traceback, error handling 831 M*/ 832 #define PetscFunctionReturn(a) \ 833 do { \ 834 PetscStackPopNoCheck; \ 835 return(a);} while (0) 836 837 #define PetscFunctionReturnVoid() \ 838 do { \ 839 PetscStackPopNoCheck; \ 840 return;} while (0) 841 842 #else 843 844 PETSC_STATIC_INLINE PetscBool PetscStackActive(void) {return PETSC_FALSE;} 845 #define PetscStackPushNoCheck(funct,petsc_routine,hot) do {} while (0) 846 #define PetscStackPopNoCheck do {} while (0) 847 #define PetscFunctionBegin 848 #define PetscFunctionBeginUser 849 #define PetscFunctionBeginHot 850 #define PetscFunctionReturn(a) return(a) 851 #define PetscFunctionReturnVoid() return 852 #define PetscStackPop CHKMEMQ 853 #define PetscStackPush(f) CHKMEMQ 854 855 #endif 856 857 /* 858 PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack. 859 860 Input Parameters: 861 + name - string that gives the name of the function being called 862 - routine - actual call to the routine, including ierr = and CHKERRQ(ierr); 863 864 Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes 865 866 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. 867 868 869 870 */ 871 #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while(0) 872 873 /* 874 PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack. 875 876 Input Parameters: 877 + func- name of the routine 878 - args - arguments to the routine surrounded by () 879 880 Notes: This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not. 881 882 Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 883 884 */ 885 #define PetscStackCallStandard(func,args) do { \ 886 PetscStackPush(#func);ierr = func args;PetscStackPop; if (ierr) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s()",#func); \ 887 } while (0) 888 889 PETSC_EXTERN PetscErrorCode PetscStackCreate(void); 890 PETSC_EXTERN PetscErrorCode PetscStackView(FILE*); 891 PETSC_EXTERN PetscErrorCode PetscStackDestroy(void); 892 893 #endif 894