1 /* 2 Contains all error handling interfaces for PETSc. 3 */ 4 #if !defined(PETSCERROR_H) 5 #define PETSCERROR_H 6 7 #include <petscmacros.h> 8 #include <petscsystypes.h> 9 10 /* SUBMANSEC = Sys */ 11 12 /* 13 These are the generic error codes. These error codes are used 14 many different places in the PETSc source code. The string versions are 15 at src/sys/error/err.c any changes here must also be made there 16 These are also define in src/sys/f90-mod/petscerror.h any CHANGES here 17 must be also made there. 18 19 */ 20 #define PETSC_ERR_MIN_VALUE 54 /* should always be one less then the smallest value */ 21 22 #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */ 23 #define PETSC_ERR_SUP 56 /* no support for requested operation */ 24 #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */ 25 #define PETSC_ERR_ORDER 58 /* operation done in wrong order */ 26 #define PETSC_ERR_SIG 59 /* signal received */ 27 #define PETSC_ERR_FP 72 /* floating point exception */ 28 #define PETSC_ERR_COR 74 /* corrupted PETSc object */ 29 #define PETSC_ERR_LIB 76 /* error in library called by PETSc */ 30 #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */ 31 #define PETSC_ERR_MEMC 78 /* memory corruption */ 32 #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */ 33 #define PETSC_ERR_USER 83 /* user has not provided needed function */ 34 #define PETSC_ERR_SYS 88 /* error in system call */ 35 #define PETSC_ERR_POINTER 70 /* pointer does not point to valid address */ 36 #define PETSC_ERR_MPI_LIB_INCOMP 87 /* MPI library at runtime is not compatible with MPI user compiled with */ 37 38 #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */ 39 #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */ 40 #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */ 41 #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */ 42 #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */ 43 #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */ 44 #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */ 45 #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */ 46 #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */ 47 #define PETSC_ERR_ARG_TYPENOTSET 89 /* the type of the object has not yet been set */ 48 #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */ 49 #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */ 50 #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */ 51 52 #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */ 53 #define PETSC_ERR_FILE_READ 66 /* unable to read from file */ 54 #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */ 55 #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */ 56 57 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 58 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 59 60 #define PETSC_ERR_INT_OVERFLOW 84 61 62 #define PETSC_ERR_FLOP_COUNT 90 63 #define PETSC_ERR_NOT_CONVERGED 91 /* solver did not converge */ 64 #define PETSC_ERR_MISSING_FACTOR 92 /* MatGetFactor() failed */ 65 #define PETSC_ERR_OPT_OVERWRITE 93 /* attempted to over write options which should not be changed */ 66 #define PETSC_ERR_WRONG_MPI_SIZE 94 /* example/application run with number of MPI ranks it does not support */ 67 #define PETSC_ERR_USER_INPUT 95 /* missing or incorrect user input */ 68 #define PETSC_ERR_GPU_RESOURCE 96 /* unable to load a GPU resource, for example cuBLAS */ 69 #define PETSC_ERR_GPU 97 /* An error from a GPU call, this may be due to lack of resources on the GPU or a true error in the call */ 70 #define PETSC_ERR_MPI 98 /* general MPI error */ 71 #define PETSC_ERR_MAX_VALUE 99 /* this is always the one more than the largest error code */ 72 73 #define SETERRQ1(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 74 #define SETERRQ2(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 75 #define SETERRQ3(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 76 #define SETERRQ4(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 77 #define SETERRQ5(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 78 #define SETERRQ6(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 79 #define SETERRQ7(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 80 #define SETERRQ8(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 81 #define SETERRQ9(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 82 83 /*MC 84 SETERRQ - Macro to be called when an error has been detected, 85 86 Synopsis: 87 #include <petscsys.h> 88 PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 89 90 Collective 91 92 Input Parameters: 93 + comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error 94 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 95 - message - error message 96 97 Level: beginner 98 99 Notes: 100 Once the error handler is called the calling function is then returned from with the given error code. 101 102 Experienced users can set the error handler with PetscPushErrorHandler(). 103 104 Fortran Notes: 105 SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the 106 Fortran main program. 107 108 .seealso: `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, 109 `PetscError()`, `PetscCall()`, `CHKMEMQ`, `CHKERRA()`, `PetscCallMPI()` 110 M*/ 111 #define SETERRQ(comm,ierr,...) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__) 112 113 /* 114 Returned from PETSc functions that are called from MPI, such as related to attributes 115 Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as 116 an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call. 117 */ 118 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS; 119 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE; 120 121 /*MC 122 SETERRMPI - Macro to be called when an error has been detected within an MPI callback function 123 124 Synopsis: 125 #include <petscsys.h> 126 PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 127 128 Collective 129 130 Input Parameters: 131 + comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error 132 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 133 - message - error message 134 135 Level: developer 136 137 Notes: 138 This macro is FOR USE IN MPI CALLBACK FUNCTIONS ONLY, such as those passed to MPI_Comm_create_keyval(). It always returns the error code PETSC_MPI_ERROR_CODE 139 which is registered with MPI_Add_error_code() when PETSc is initialized. 140 141 .seealso: `SETERRQ()`, `PetscCall()`, `PetscCallMPI()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 142 M*/ 143 #define SETERRMPI(comm,ierr,...) return (PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__),PETSC_MPI_ERROR_CODE) 144 145 /*MC 146 SETERRA - Fortran-only macro that can be called when an error has been detected from the main program 147 148 Synopsis: 149 #include <petscsys.h> 150 PetscErrorCode SETERRA(MPI_Comm comm,PetscErrorCode ierr,char *message) 151 152 Collective 153 154 Input Parameters: 155 + comm - A communicator, so that the error can be collective 156 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 157 - message - error message in the printf format 158 159 Level: beginner 160 161 Notes: 162 This should only be used with Fortran. With C/C++, use SETERRQ(). 163 164 Fortran Notes: 165 SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the 166 Fortran main program. 167 168 .seealso: `SETERRQ()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()` 169 M*/ 170 171 /*MC 172 SETERRABORT - Macro that can be called when an error has been detected, 173 174 Synopsis: 175 #include <petscsys.h> 176 PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 177 178 Collective 179 180 Input Parameters: 181 + comm - A communicator, so that the error can be collective 182 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 183 - message - error message in the printf format 184 185 Level: beginner 186 187 Notes: 188 This function just calls MPI_Abort(). 189 190 .seealso: `SETERRQ()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `PetscCall()`, `CHKMEMQ` 191 M*/ 192 #define SETERRABORT(comm,ierr,...) do { \ 193 PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__); \ 194 MPI_Abort(comm,ierr); \ 195 } while (0) 196 197 /*MC 198 PetscCheck - Check that a particular condition is true 199 200 Synopsis: 201 #include <petscerror.h> 202 void PetscCheck(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 203 204 Collective 205 206 Input Parameters: 207 + cond - The boolean condition 208 . comm - The communicator on which the check can be collective on 209 . ierr - A nonzero error code, see include/petscerror.h for the complete list 210 - message - Error message in printf format 211 212 Notes: 213 Enabled in both optimized and debug builds. 214 215 Calls SETERRQ() if the assertion fails, so can only be called from functions returning a 216 PetscErrorCode (or equivalent type after conversion). 217 218 Level: beginner 219 220 .seealso: `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()` 221 M*/ 222 #define PetscCheck(cond,comm,ierr,...) do { if (PetscUnlikely(!(cond))) SETERRQ(comm,ierr,__VA_ARGS__); } while (0) 223 224 /*MC 225 PetscAssert - Assert that a particular condition is true 226 227 Synopsis: 228 #include <petscerror.h> 229 void PetscAssert(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 230 231 Collective 232 233 Input Parameters: 234 + cond - The boolean condition 235 . comm - The communicator on which the check can be collective on 236 . ierr - A nonzero error code, see include/petscerror.h for the complete list 237 - message - Error message in printf format 238 239 Notes: 240 Enabled only in debug builds. Note that any arguments to this macros are still visible to the 241 compiler optimized builds (so must still contain valid code) but are guaranteed to not be 242 executed. 243 244 See PetscCheck() for usage and behaviour. 245 246 Level: beginner 247 248 .seealso: `PetscCheck()`, `SETERRQ()`, `PetscError()` 249 M*/ 250 #define PetscAssert(cond,comm,ierr,...) do { if (PetscUnlikelyDebug(!(cond))) SETERRQ(comm,ierr,__VA_ARGS__); } while (0) 251 252 /*MC 253 PetscCall - Calls a PETSc function and then checks the resulting error code, if it is non-zero it calls the error 254 handler and returns from the current function with the error code. 255 256 Synopsis: 257 #include <petscerror.h> 258 void PetscCall(PetscFunction(args)) 259 260 Not Collective 261 262 Input Parameter: 263 . PetscFunction - any PETSc function that returns an error code 264 265 Notes: 266 Once the error handler is called the calling function is then returned from with the given 267 error code. Experienced users can set the error handler with PetscPushErrorHandler(). 268 269 PetscCall() cannot be used in functions returning a datatype not convertible to 270 PetscErrorCode. For example, PetscCall() may not be used in functions returning void, use 271 PetscCallVoid() in this case. 272 273 Example Usage: 274 .vb 275 PetscCall(PetscInitiailize(...)); // OK to call even when PETSc is not yet initialized! 276 277 struct my_struct 278 { 279 void *data; 280 } my_complex_type; 281 282 struct my_struct bar(void) 283 { 284 PetscCall(foo(15)); // ERROR PetscErrorCode not convertible to struct my_struct! 285 } 286 287 PetscCall(bar()) // ERROR input not convertible to PetscErrorCode 288 .ve 289 290 It is also possible to call this directory on a PetscErrorCode variable 291 .vb 292 PetscCall(ierr); // check if ierr is nonzero 293 .ve 294 295 Fortran Notes: 296 The Fortran function from which this is used must declare a variable PetscErrorCode ierr and ierr must be 297 the final argument to the PetscFunction being called. 298 299 In the main program and in Fortran subroutines that do not have ierr as the final return parameter one 300 should use PetscCallA() 301 302 Example Fortran Usage: 303 .vb 304 PetscErrorCode ierr 305 Vec v 306 307 ... 308 PetscCall(VecShift(v,1.0,ierr)) 309 PetscCallA(VecShift(v,1.0,ierr)) 310 .ve 311 312 Level: beginner 313 314 .seealso: `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()` 315 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()` 316 M*/ 317 #if defined(PETSC_CLANG_STATIC_ANALYZER) 318 void PetscCall(PetscErrorCode); 319 void PetscCallVoid(PetscErrorCode); 320 #else 321 #define PetscCall(...) do { \ 322 PetscErrorCode ierr_q_ = __VA_ARGS__; \ 323 if (PetscUnlikely(ierr_q_)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_q_,PETSC_ERROR_REPEAT," "); \ 324 } while (0) 325 #define PetscCallVoid(...) do { \ 326 PetscErrorCode ierr_void_ = __VA_ARGS__; \ 327 if (PetscUnlikely(ierr_void_)) { \ 328 (void)PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_void_,PETSC_ERROR_REPEAT," "); \ 329 return; \ 330 } \ 331 } while (0) 332 #endif 333 334 /*MC 335 CHKERRQ - Checks error code returned from PETSc function 336 337 Synopsis: 338 #include <petscsys.h> 339 void CHKERRQ(PetscErrorCode ierr) 340 341 Not Collective 342 343 Input Parameters: 344 . ierr - nonzero error code 345 346 Notes: 347 Deprecated in favor of PetscCall(). This routine behaves identically to it. 348 349 Level: deprecated 350 351 .seealso: `PetscCall()` 352 M*/ 353 #define CHKERRQ(...) PetscCall(__VA_ARGS__) 354 #define CHKERRV(...) PetscCallVoid(__VA_ARGS__) 355 356 PETSC_EXTERN void PetscMPIErrorString(PetscMPIInt, char*); 357 358 /*MC 359 PetscCallMPI - Checks error code returned from MPI calls, if non-zero it calls the error 360 handler and then returns 361 362 Synopsis: 363 #include <petscerror.h> 364 void PetscCallMPI(MPI_Function(args)) 365 366 Not Collective 367 368 Input Parameters: 369 . MPI_Function - an MPI function that returns an MPI error code 370 371 Notes: 372 Always returns the error code PETSC_ERR_MPI; the MPI error code and string are embedded in 373 the string error message. Do not use this to call any other routines (for example PETSc 374 routines), it should only be used for direct MPI calls. Due to limitations of the 375 preprocessor this can unfortunately not easily be enforced, so the user should take care to 376 check this themselves. 377 378 Example Usage: 379 .vb 380 PetscCallMPI(MPI_Comm_size(...)); // OK, calling MPI function 381 382 PetscCallMPI(PetscFunction(...)); // ERROR, use PetscCall() instead! 383 .ve 384 385 Fortran Notes: 386 The Fortran function from which this is used must declare a variable PetscErrorCode ierr and ierr must be 387 the final argument to the MPI function being called. 388 389 In the main program and in Fortran subroutines that do not have ierr as the final return parameter one 390 should use PetscCallMPIA() 391 392 Fortran Usage: 393 .vb 394 PetscErrorCode ierr or integer ierr 395 ... 396 PetscCallMPI(MPI_Comm_size(...,ierr)) 397 PetscCallMPIA(MPI_Comm_size(...,ierr)) ! Will abort after calling error handler 398 399 PetscCallMPI(MPI_Comm_size(...,eflag)) ! ERROR, final argument must be ierr 400 .ve 401 402 Level: beginner 403 404 .seealso: `SETERRMPI()`, `PetscCall()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`, 405 `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 406 M*/ 407 #if defined(PETSC_CLANG_STATIC_ANALYZER) 408 void PetscCallMPI(PetscMPIInt); 409 #else 410 #define PetscCallMPI(...) do { \ 411 PetscMPIInt _7_errorcode = __VA_ARGS__; \ 412 if (PetscUnlikely(_7_errorcode)) { \ 413 char _7_errorstring[2*MPI_MAX_ERROR_STRING]; \ 414 PetscMPIErrorString(_7_errorcode,(char*)_7_errorstring); \ 415 SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MPI,"MPI error %d %s",(int)_7_errorcode,_7_errorstring); \ 416 } \ 417 } while (0) 418 #endif 419 420 /*MC 421 CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error 422 handler and then returns 423 424 Synopsis: 425 #include <petscerror.h> 426 void CHKERRMPI(PetscErrorCode ierr) 427 428 Not Collective 429 430 Input Parameter: 431 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 432 433 Notes: 434 Deprecated in favor of PetscCallMPI(). This routine behaves identically to it. 435 436 Level: deprecated 437 438 .seealso: `PetscCallMPI()` 439 M*/ 440 #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__) 441 442 /*MC 443 PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately 444 445 Synopsis: 446 #include <petscerror.h> 447 void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr) 448 449 Collective on comm 450 451 Input Parameters: 452 + comm - the MPI communicator on which to abort 453 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 454 455 Notes: 456 This macro has identical type and usage semantics to PetscCall() with the important caveat 457 that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler 458 and then immediately calls MPI_Abort(). It can therefore be used anywhere. 459 460 As per MPI_Abort semantics the communicator passed must be valid, although there is currently 461 no attempt made at handling any potential errors from MPI_Abort(). Note that while 462 MPI_Abort() is required to terminate only those processes which reside on comm, it is often 463 the case that MPI_Abort() terminates *all* processes. 464 465 Example Usage: 466 .vb 467 PetscErrorCode boom(void) { return PETSC_ERR_MEM; } 468 469 void foo(void) 470 { 471 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 472 } 473 474 double bar(void) 475 { 476 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 477 } 478 479 PetscCallAbort(MPI_COMM_NULL,boom()); // ERROR, communicator should be valid 480 481 struct baz 482 { 483 baz() 484 { 485 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK 486 } 487 488 ~baz() 489 { 490 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK (in fact the only way to handle PETSc errors) 491 } 492 }; 493 .ve 494 495 Level: intermediate 496 497 .seealso: `SETERRABORT()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, 498 `SETERRQ()`, `CHKMEMQ`, `PetscCallMPI()` 499 M*/ 500 #if defined(PETSC_CLANG_STATIC_ANALYZER) 501 void PetscCallAbort(MPI_Comm,PetscErrorCode); 502 void PetscCallContinue(PetscErrorCode); 503 #else 504 #define PetscCallAbort(comm,...) do { \ 505 PetscErrorCode ierr_abort_ = __VA_ARGS__; \ 506 if (PetscUnlikely(ierr_abort_)) { \ 507 PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_abort_,PETSC_ERROR_REPEAT," "); \ 508 MPI_Abort(comm,ierr_abort_); \ 509 } \ 510 } while (0) 511 #define PetscCallContinue(...) do { \ 512 PetscErrorCode ierr_continue_ = __VA_ARGS__; \ 513 if (PetscUnlikely(ierr_continue_)) PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_continue_,PETSC_ERROR_REPEAT," "); \ 514 } while (0) 515 #endif 516 517 /*MC 518 CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately. 519 520 Synopsis: 521 #include <petscerror.h> 522 void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr) 523 524 Not Collective 525 526 Input Parameters: 527 + comm - the MPI communicator 528 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 529 530 Notes: 531 Deprecated in favor of PetscCallAbort(). This routine behaves identically to it. 532 533 Level: deprecated 534 535 .seealso: `PetscCallAbort()` 536 M*/ 537 #define CHKERRABORT(comm,...) PetscCallAbort(comm,__VA_ARGS__) 538 #define CHKERRCONTINUE(...) PetscCallContinue(__VA_ARGS__) 539 540 /*MC 541 CHKERRA - Fortran-only replacement for PetscCall in the main program, which aborts immediately 542 543 Synopsis: 544 #include <petscsys.h> 545 PetscErrorCode CHKERRA(PetscErrorCode ierr) 546 547 Not Collective 548 549 Input Parameters: 550 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 551 552 Level: beginner 553 554 Notes: 555 This should only be used with Fortran. With C/C++, use PetscCall() in normal usage, 556 or PetscCallAbort() if wanting to abort immediately on error. 557 558 Fortran Notes: 559 PetscCall() may be called from Fortran subroutines but CHKERRA() must be called from the 560 Fortran main program. 561 562 .seealso: `PetscCall()`, `PetscCallAbort()`, `SETERRA()`, `SETERRQ()`, `SETERRABORT()` 563 M*/ 564 565 PETSC_EXTERN PetscErrorCode PetscAbortFindSourceFile_Private(const char*,PetscInt*); 566 PETSC_EXTERN PetscBool petscwaitonerrorflg; 567 PETSC_EXTERN PetscBool petscindebugger; 568 569 /*MC 570 PETSCABORT - Call MPI_Abort with an informative error code 571 572 Synopsis: 573 #include <petscsys.h> 574 PETSCABORT(MPI_Comm comm, PetscErrorCode ierr) 575 576 Collective 577 578 Input Parameters: 579 + comm - A communicator, so that the error can be collective 580 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 581 582 Level: advanced 583 584 Notes: 585 We pass MPI_Abort() an error code of format XX_YYYY_ZZZ, where XX, YYYY are an index and line number of the file 586 where PETSCABORT is called, respectively. ZZZ is the PETSc error code. 587 588 If XX is zero, this means that the call was made in the routine main(). 589 If XX is one, that means 1) the file is not in PETSc (it may be in users code); OR 2) the file is in PETSc but PetscAbortSourceFiles[] 590 is out of date. PETSc developers have to update it. 591 Otherwise, look up the value of XX in the table PetscAbortSourceFiles[] in src/sys/error/err.c to map XX back to the source file where the PETSCABORT() was called. 592 593 If the option -start_in_debugger was used then this calls abort() to stop the program in the debugger. 594 595 M*/ 596 #define PETSCABORT(comm,...) do { \ 597 if (petscwaitonerrorflg) PetscSleep(1000); \ 598 if (petscindebugger) abort(); \ 599 else { \ 600 PetscErrorCode ierr_petsc_abort_ = __VA_ARGS__; \ 601 PetscInt idx = 0; \ 602 PetscAbortFindSourceFile_Private(__FILE__,&idx); \ 603 MPI_Abort(comm,(PetscMPIInt)(0*idx*10000000 + 0*__LINE__*1000 + ierr_petsc_abort_)); \ 604 } \ 605 } while (0) 606 607 #ifdef PETSC_CLANGUAGE_CXX 608 /*MC 609 PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws 610 an exception 611 612 Synopsis: 613 #include <petscerror.h> 614 void PetscCallThrow(PetscErrorCode ierr) 615 616 Not Collective 617 618 Input Parameter: 619 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 620 621 Notes: 622 Requires PETSc to be configured with clanguage = c++. Throws a std::runtime_error() on error. 623 624 Once the error handler throws the exception you can use PetscCallVoid() which returns without 625 an error code (bad idea since the error is ignored) or PetscCallAbort() to have MPI_Abort() 626 called immediately. 627 628 Level: beginner 629 630 .seealso: `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`, 631 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 632 M*/ 633 #define PetscCallThrow(...) do { \ 634 PetscErrorCode ierr_cxx_ = __VA_ARGS__; \ 635 if (PetscUnlikely(ierr_cxx_)) PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_cxx_,PETSC_ERROR_IN_CXX,PETSC_NULLPTR); \ 636 } while (0) 637 638 /*MC 639 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception 640 641 Synopsis: 642 #include <petscerror.h> 643 void CHKERRXX(PetscErrorCode ierr) 644 645 Not Collective 646 647 Input Parameter: 648 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 649 650 Notes: 651 Deprecated in favor of PetscCallThrow(). This routine behaves identically to it. 652 653 Level: deprecated 654 655 .seealso: `PetscCallThrow()` 656 M*/ 657 #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__) 658 #endif 659 660 /*MC 661 PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then 662 return a PETSc error code 663 664 Synopsis: 665 #include <petscerror.h> 666 void PetscCallCXX(expr) noexcept; 667 668 Not Collective 669 670 Input Parameter: 671 . expr - An arbitrary expression 672 673 Notes: 674 PetscCallCXX(expr) is a macro replacement for 675 .vb 676 try { 677 expr; 678 } catch (const std::exception& e) { 679 return ConvertToPetscErrorCode(e); 680 } 681 .ve 682 Due to the fact that it catches any (reasonable) exception, it is essentially noexcept. 683 684 Example Usage: 685 .vb 686 void foo(void) { throw std::runtime_error("error"); } 687 688 void bar() 689 { 690 PetscCallCXX(foo()); // ERROR bar() does not return PetscErrorCode 691 } 692 693 PetscErrorCode baz() 694 { 695 PetscCallCXX(foo()); // OK 696 697 PetscCallCXX( 698 bar(); 699 foo(); // OK mutliple statements allowed 700 ); 701 } 702 703 struct bop 704 { 705 bop() 706 { 707 PetscCallCXX(foo()); // ERROR returns PetscErrorCode, cannot be used in constructors 708 } 709 }; 710 711 // ERROR contains do-while, cannot be used as function-try block 712 PetscErrorCode qux() PetscCallCXX( 713 bar(); 714 baz(); 715 foo(); 716 return 0; 717 ) 718 .ve 719 720 Level: beginner 721 722 .seealso: `PetscCallThrow()`, `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, 723 `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 724 M*/ 725 #define PetscCallCXX(...) do { \ 726 try { \ 727 __VA_ARGS__; \ 728 } catch (const std::exception& e) { \ 729 SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"%s",e.what()); \ 730 } \ 731 } while (0) 732 733 /*MC 734 CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then 735 return a PETSc error code 736 737 Synopsis: 738 #include <petscerror.h> 739 void CHKERRCXX(func) noexcept; 740 741 Not Collective 742 743 Input Parameter: 744 . func - C++ function calls 745 746 Notes: 747 Deprecated in favor of PetscCallCXX(). This routine behaves identically to it. 748 749 Level: deprecated 750 751 .seealso: `PetscCallCXX()` 752 M*/ 753 #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__) 754 755 /*MC 756 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 757 758 Synopsis: 759 #include <petscsys.h> 760 CHKMEMQ; 761 762 Not Collective 763 764 Level: beginner 765 766 Notes: 767 We highly recommend using Valgrind https://petsc.org/release/faq/#valgrind or for NVIDIA CUDA systems 768 https://docs.nvidia.com/cuda/cuda-memcheck/index.html for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that 769 do not have valgrind, but is not as good as valgrind or cuda-memcheck. 770 771 Must run with the option -malloc_debug (-malloc_test in debug mode; or if PetscMallocSetDebug() called) to enable this option 772 773 Once the error handler is called the calling function is then returned from with the given error code. 774 775 By defaults prints location where memory that is corrupted was allocated. 776 777 Use CHKMEMA for functions that return void 778 779 .seealso: `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `SETERRQ()`, `PetscMallocValidate()` 780 M*/ 781 #if defined(PETSC_CLANG_STATIC_ANALYZER) 782 #define CHKMEMQ 783 #define CHKMEMA 784 #else 785 #define CHKMEMQ PetscCall(PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__)); 786 #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__) 787 #endif 788 789 /*E 790 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 791 792 Level: advanced 793 794 PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated 795 796 Developer Notes: 797 This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 798 799 .seealso: `PetscError()`, `SETERRXX()` 800 E*/ 801 typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType; 802 803 #if defined(__clang_analyzer__) 804 __attribute__((analyzer_noreturn)) 805 #endif 806 PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7,8); 807 808 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 809 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **); 810 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 811 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 812 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 813 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 814 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 815 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 816 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD; 817 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*); 818 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 819 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*); 820 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 821 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 822 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 823 PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void); 824 PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") static inline void PetscSignalSegvCheckPointer(void) {PetscSignalSegvCheckPointerOrMpi();} 825 826 /*MC 827 PetscErrorPrintf - Prints error messages. 828 829 Synopsis: 830 #include <petscsys.h> 831 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 832 833 Not Collective 834 835 Input Parameter: 836 . format - the usual printf() format string 837 838 Options Database Keys: 839 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 840 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 841 842 Notes: 843 Use 844 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 845 $ error is handled.) and 846 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 847 848 Use 849 PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file. 850 PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file. 851 852 Use 853 PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print 854 855 Level: developer 856 857 Fortran Note: 858 This routine is not supported in Fortran. 859 860 .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscHelpPrintf()`, `PetscPrintf()`, `PetscPushErrorHandler()`, `PetscVFPrintf()`, `PetscHelpPrintf()` 861 M*/ 862 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...) PETSC_ATTRIBUTE_FORMAT(1,2); 863 864 /*E 865 PetscFPTrap - types of floating point exceptions that may be trapped 866 867 Currently only PETSC_FP_TRAP_OFF and PETSC_FP_TRAP_ON are handled. All others are treated as PETSC_FP_TRAP_ON. 868 869 Level: intermediate 870 871 .seealso: `PetscSetFPTrap()`, `PetscPushFPTrap()` 872 E*/ 873 typedef enum {PETSC_FP_TRAP_OFF=0, PETSC_FP_TRAP_INDIV=1, PETSC_FP_TRAP_FLTOPERR=2, PETSC_FP_TRAP_FLTOVF=4, PETSC_FP_TRAP_FLTUND=8, PETSC_FP_TRAP_FLTDIV=16, PETSC_FP_TRAP_FLTINEX=32} PetscFPTrap; 874 #define PETSC_FP_TRAP_ON (PETSC_FP_TRAP_INDIV | PETSC_FP_TRAP_FLTOPERR | PETSC_FP_TRAP_FLTOVF | PETSC_FP_TRAP_FLTDIV | PETSC_FP_TRAP_FLTINEX) 875 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 876 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 877 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 878 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void); 879 880 /* 881 Allows the code to build a stack frame as it runs 882 */ 883 884 #if defined(PETSC_USE_DEBUG) 885 #define PETSCSTACKSIZE 64 886 typedef struct { 887 const char *function[PETSCSTACKSIZE]; 888 const char *file[PETSCSTACKSIZE]; 889 int line[PETSCSTACKSIZE]; 890 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */ 891 int currentsize; 892 int hotdepth; 893 PetscBool check; /* runtime option to check for correct Push/Pop semantics at runtime */ 894 } PetscStack; 895 PETSC_EXTERN PetscStack petscstack; 896 #else 897 typedef struct { 898 char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp; 899 } PetscStack; 900 #endif 901 902 #if defined(PETSC_SERIALIZE_FUNCTIONS) 903 #include <petsc/private/petscfptimpl.h> 904 /* 905 Registers the current function into the global function pointer to function name table 906 907 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 908 */ 909 #define PetscRegister__FUNCT__() do { \ 910 static PetscBool __chked = PETSC_FALSE; \ 911 if (!__chked) {\ 912 void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\ 913 __chked = PETSC_TRUE;\ 914 }} while (0) 915 #else 916 #define PetscRegister__FUNCT__() 917 #endif 918 919 #if defined(PETSC_CLANG_STATIC_ANALYZER) 920 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 921 #define PetscStackPopNoCheck 922 #define PetscStackClearTop 923 #define PetscFunctionBegin 924 #define PetscFunctionBeginUser 925 #define PetscFunctionBeginHot 926 #define PetscFunctionReturn(a) return a 927 #define PetscFunctionReturnVoid() return 928 #define PetscStackPop 929 #define PetscStackPush(f) 930 #elif defined(PETSC_USE_DEBUG) 931 #define PetscStackPush_Private(stack__,file__,func__,line__,petsc_routine__,hot__) do { \ 932 if (stack__.currentsize < PETSCSTACKSIZE) { \ 933 stack__.file[stack__.currentsize] = file__; \ 934 stack__.function[stack__.currentsize] = func__; \ 935 stack__.line[stack__.currentsize] = line__; \ 936 stack__.petscroutine[stack__.currentsize] = petsc_routine__; \ 937 } \ 938 ++stack__.currentsize; \ 939 stack__.hotdepth += (hot__ || stack__.hotdepth); \ 940 } while (0) 941 942 #define PetscStackPop_Private(stack__,func__) do { \ 943 if (PetscUnlikely(stack__.currentsize <= 0)) { \ 944 if (PetscUnlikely(stack__.check)) { \ 945 printf("Invalid stack size %d, pop %s\n",stack__.currentsize,func__); \ 946 } \ 947 } else { \ 948 if (--stack__.currentsize < PETSCSTACKSIZE) { \ 949 if (PetscUnlikely( \ 950 stack__.check && \ 951 stack__.petscroutine[stack__.currentsize] && \ 952 (stack__.function[stack__.currentsize] != (const char*)(func__)))) { \ 953 /* We need this string comparison because "unknown" can be defined in different static strings: */ \ 954 PetscBool _cmpflg; \ 955 const char *_funct = stack__.function[stack__.currentsize]; \ 956 PetscStrcmp(_funct,func__,&_cmpflg); \ 957 if (!_cmpflg) printf("Invalid stack: push from %s, pop from %s\n",_funct,func__); \ 958 } \ 959 stack__.function[stack__.currentsize] = PETSC_NULLPTR; \ 960 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 961 stack__.line[stack__.currentsize] = 0; \ 962 stack__.petscroutine[stack__.currentsize] = 0; \ 963 } \ 964 stack__.hotdepth = PetscMax(stack__.hotdepth-1,0); \ 965 } \ 966 } while (0) 967 968 /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error 969 * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at 970 * least more useful than "unknown" because it can distinguish multiple calls from the same function. 971 */ 972 #define PetscStackPushNoCheck(funct,petsc_routine,hot) do { \ 973 PetscStackSAWsTakeAccess(); \ 974 PetscStackPush_Private(petscstack,__FILE__,funct,__LINE__,petsc_routine,hot); \ 975 PetscStackSAWsGrantAccess(); \ 976 } while (0) 977 978 #define PetscStackPopNoCheck(funct) do { \ 979 PetscStackSAWsTakeAccess(); \ 980 PetscStackPop_Private(petscstack,funct); \ 981 PetscStackSAWsGrantAccess(); \ 982 } while (0) 983 984 #define PetscStackClearTop do { \ 985 PetscStackSAWsTakeAccess(); \ 986 if (petscstack.currentsize > 0 && \ 987 --petscstack.currentsize < PETSCSTACKSIZE) { \ 988 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 989 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 990 petscstack.line[petscstack.currentsize] = 0; \ 991 petscstack.petscroutine[petscstack.currentsize] = 0; \ 992 } \ 993 petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \ 994 PetscStackSAWsGrantAccess(); \ 995 } while (0) 996 997 /*MC 998 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 999 line of PETSc functions should be PetscFunctionReturn(0); 1000 1001 Synopsis: 1002 #include <petscsys.h> 1003 void PetscFunctionBegin; 1004 1005 Not Collective 1006 1007 Usage: 1008 .vb 1009 int something; 1010 1011 PetscFunctionBegin; 1012 .ve 1013 1014 Notes: 1015 Use PetscFunctionBeginUser for application codes. 1016 1017 Not available in Fortran 1018 1019 Level: developer 1020 1021 .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()` 1022 1023 M*/ 1024 #define PetscFunctionBegin do { \ 1025 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_FALSE); \ 1026 PetscRegister__FUNCT__(); \ 1027 } while (0) 1028 1029 /*MC 1030 PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in 1031 performance-critical circumstances. Use of this function allows for lighter profiling by default. 1032 1033 Synopsis: 1034 #include <petscsys.h> 1035 void PetscFunctionBeginHot; 1036 1037 Not Collective 1038 1039 Usage: 1040 .vb 1041 int something; 1042 1043 PetscFunctionBeginHot; 1044 .ve 1045 1046 Notes: 1047 Not available in Fortran 1048 1049 Level: developer 1050 1051 .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()` 1052 1053 M*/ 1054 #define PetscFunctionBeginHot do { \ 1055 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_TRUE); \ 1056 PetscRegister__FUNCT__(); \ 1057 } while (0) 1058 1059 /*MC 1060 PetscFunctionBeginUser - First executable line of user provided PETSc routine 1061 1062 Synopsis: 1063 #include <petscsys.h> 1064 void PetscFunctionBeginUser; 1065 1066 Not Collective 1067 1068 Usage: 1069 .vb 1070 int something; 1071 1072 PetscFunctionBeginUser; 1073 .ve 1074 1075 Notes: 1076 Final line of PETSc functions should be PetscFunctionReturn(0) except for main(). 1077 1078 Not available in Fortran 1079 1080 This is identical to PetscFunctionBegin except it labels the routine as a user 1081 routine instead of as a PETSc library routine. 1082 1083 Level: intermediate 1084 1085 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot` 1086 1087 M*/ 1088 #define PetscFunctionBeginUser do { \ 1089 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,2,PETSC_FALSE); \ 1090 PetscRegister__FUNCT__(); \ 1091 } while (0) 1092 1093 #define PetscStackPush(n) do { \ 1094 PetscStackPushNoCheck(n,0,PETSC_FALSE); \ 1095 CHKMEMQ; \ 1096 } while (0) 1097 1098 #define PetscStackPop do { \ 1099 CHKMEMQ; \ 1100 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1101 } while (0) 1102 1103 /*MC 1104 PetscFunctionReturn - Last executable line of each PETSc function 1105 used for error handling. Replaces return() 1106 1107 Synopsis: 1108 #include <petscsys.h> 1109 void PetscFunctionReturn(0); 1110 1111 Not Collective 1112 1113 Usage: 1114 .vb 1115 .... 1116 PetscFunctionReturn(0); 1117 } 1118 .ve 1119 1120 Notes: 1121 Not available in Fortran 1122 1123 Level: developer 1124 1125 .seealso: `PetscFunctionBegin()` 1126 1127 M*/ 1128 #define PetscFunctionReturn(a) do { \ 1129 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1130 return a; \ 1131 } while (0) 1132 1133 #define PetscFunctionReturnVoid() do { \ 1134 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1135 return; \ 1136 } while (0) 1137 #else /* PETSC_USE_DEBUG */ 1138 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 1139 #define PetscStackPopNoCheck 1140 #define PetscStackClearTop 1141 #define PetscFunctionBegin 1142 #define PetscFunctionBeginUser 1143 #define PetscFunctionBeginHot 1144 #define PetscFunctionReturn(a) return a 1145 #define PetscFunctionReturnVoid() return 1146 #define PetscStackPop CHKMEMQ 1147 #define PetscStackPush(f) CHKMEMQ 1148 #endif /* PETSC_USE_DEBUG */ 1149 1150 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1151 #define PetscStackCall(name,routine) 1152 #define PetscStackCallStandard(func,...) 1153 #else 1154 /* 1155 PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack. 1156 1157 Input Parameters: 1158 + name - string that gives the name of the function being called 1159 - routine - actual call to the routine, including ierr = and PetscCall(ierr); 1160 1161 Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes 1162 1163 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. 1164 1165 */ 1166 #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while (0) 1167 1168 /* 1169 PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack. 1170 1171 Input Parameters: 1172 + func- name of the routine 1173 - args - arguments to the routine surrounded by () 1174 1175 Notes: 1176 This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not. 1177 1178 Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1179 1180 */ 1181 #define PetscStackCallStandard(func,...) do { \ 1182 PetscStackPush(PetscStringize(func)); \ 1183 PetscErrorCode __ierr = func(__VA_ARGS__); \ 1184 PetscStackPop; \ 1185 PetscCheck(!__ierr,PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",PetscStringize(func),__ierr); \ 1186 } while (0) 1187 #endif /* PETSC_CLANG_STATIC_ANALYZER */ 1188 1189 #endif 1190