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,...) if (PetscUnlikely(!(cond))) SETERRQ(comm,ierr,__VA_ARGS__) 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,...) if (PetscUnlikelyDebug(!(cond))) SETERRQ(comm,ierr,__VA_ARGS__) 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 convertable 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 convertable to struct my_struct! 285 } 286 287 PetscCall(bar()) // ERROR input not convertable 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 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 865 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 866 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 867 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 868 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void); 869 870 /* 871 Allows the code to build a stack frame as it runs 872 */ 873 874 #if defined(PETSC_USE_DEBUG) 875 #define PETSCSTACKSIZE 64 876 typedef struct { 877 const char *function[PETSCSTACKSIZE]; 878 const char *file[PETSCSTACKSIZE]; 879 int line[PETSCSTACKSIZE]; 880 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */ 881 int currentsize; 882 int hotdepth; 883 PetscBool check; /* runtime option to check for correct Push/Pop semantics at runtime */ 884 } PetscStack; 885 PETSC_EXTERN PetscStack petscstack; 886 #else 887 typedef struct { 888 char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp; 889 } PetscStack; 890 #endif 891 892 #if defined(PETSC_SERIALIZE_FUNCTIONS) 893 #include <petsc/private/petscfptimpl.h> 894 /* 895 Registers the current function into the global function pointer to function name table 896 897 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 898 */ 899 #define PetscRegister__FUNCT__() do { \ 900 static PetscBool __chked = PETSC_FALSE; \ 901 if (!__chked) {\ 902 void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\ 903 __chked = PETSC_TRUE;\ 904 }} while (0) 905 #else 906 #define PetscRegister__FUNCT__() 907 #endif 908 909 #if defined(PETSC_CLANG_STATIC_ANALYZER) 910 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 911 #define PetscStackPopNoCheck 912 #define PetscStackClearTop 913 #define PetscFunctionBegin 914 #define PetscFunctionBeginUser 915 #define PetscFunctionBeginHot 916 #define PetscFunctionReturn(a) return a 917 #define PetscFunctionReturnVoid() return 918 #define PetscStackPop 919 #define PetscStackPush(f) 920 #elif defined(PETSC_USE_DEBUG) 921 #define PetscStackPush_Private(stack__,file__,func__,line__,petsc_routine__,hot__) do { \ 922 if (stack__.currentsize < PETSCSTACKSIZE) { \ 923 stack__.file[stack__.currentsize] = file__; \ 924 stack__.function[stack__.currentsize] = func__; \ 925 stack__.line[stack__.currentsize] = line__; \ 926 stack__.petscroutine[stack__.currentsize] = petsc_routine__; \ 927 } \ 928 ++stack__.currentsize; \ 929 stack__.hotdepth += (hot__ || stack__.hotdepth); \ 930 } while (0) 931 932 #define PetscStackPop_Private(stack__,func__) do { \ 933 if (PetscUnlikely(stack__.currentsize <= 0)) { \ 934 if (PetscUnlikely(stack__.check)) { \ 935 printf("Invalid stack size %d, pop %s\n",stack__.currentsize,func__); \ 936 } \ 937 } else { \ 938 if (--stack__.currentsize < PETSCSTACKSIZE) { \ 939 if (PetscUnlikely( \ 940 stack__.check && \ 941 stack__.petscroutine[stack__.currentsize] && \ 942 (stack__.function[stack__.currentsize] != (const char*)(func__)))) { \ 943 /* We need this string comparison because "unknown" can be defined in different static strings: */ \ 944 PetscBool _cmpflg; \ 945 const char *_funct = stack__.function[stack__.currentsize]; \ 946 PetscStrcmp(_funct,func__,&_cmpflg); \ 947 if (!_cmpflg) printf("Invalid stack: push from %s, pop from %s\n",_funct,func__); \ 948 } \ 949 stack__.function[stack__.currentsize] = PETSC_NULLPTR; \ 950 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 951 stack__.line[stack__.currentsize] = 0; \ 952 stack__.petscroutine[stack__.currentsize] = 0; \ 953 } \ 954 stack__.hotdepth = PetscMax(stack__.hotdepth-1,0); \ 955 } \ 956 } while (0) 957 958 /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error 959 * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at 960 * least more useful than "unknown" because it can distinguish multiple calls from the same function. 961 */ 962 #define PetscStackPushNoCheck(funct,petsc_routine,hot) do { \ 963 PetscStackSAWsTakeAccess(); \ 964 PetscStackPush_Private(petscstack,__FILE__,funct,__LINE__,petsc_routine,hot); \ 965 PetscStackSAWsGrantAccess(); \ 966 } while (0) 967 968 #define PetscStackPopNoCheck(funct) do { \ 969 PetscStackSAWsTakeAccess(); \ 970 PetscStackPop_Private(petscstack,funct); \ 971 PetscStackSAWsGrantAccess(); \ 972 } while (0) 973 974 #define PetscStackClearTop do { \ 975 PetscStackSAWsTakeAccess(); \ 976 if (petscstack.currentsize > 0 && \ 977 --petscstack.currentsize < PETSCSTACKSIZE) { \ 978 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 979 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 980 petscstack.line[petscstack.currentsize] = 0; \ 981 petscstack.petscroutine[petscstack.currentsize] = 0; \ 982 } \ 983 petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \ 984 PetscStackSAWsGrantAccess(); \ 985 } while (0) 986 987 /*MC 988 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 989 line of PETSc functions should be PetscFunctionReturn(0); 990 991 Synopsis: 992 #include <petscsys.h> 993 void PetscFunctionBegin; 994 995 Not Collective 996 997 Usage: 998 .vb 999 int something; 1000 1001 PetscFunctionBegin; 1002 .ve 1003 1004 Notes: 1005 Use PetscFunctionBeginUser for application codes. 1006 1007 Not available in Fortran 1008 1009 Level: developer 1010 1011 .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()` 1012 1013 M*/ 1014 #define PetscFunctionBegin do { \ 1015 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_FALSE); \ 1016 PetscRegister__FUNCT__(); \ 1017 } while (0) 1018 1019 /*MC 1020 PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in 1021 performance-critical circumstances. Use of this function allows for lighter profiling by default. 1022 1023 Synopsis: 1024 #include <petscsys.h> 1025 void PetscFunctionBeginHot; 1026 1027 Not Collective 1028 1029 Usage: 1030 .vb 1031 int something; 1032 1033 PetscFunctionBeginHot; 1034 .ve 1035 1036 Notes: 1037 Not available in Fortran 1038 1039 Level: developer 1040 1041 .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()` 1042 1043 M*/ 1044 #define PetscFunctionBeginHot do { \ 1045 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_TRUE); \ 1046 PetscRegister__FUNCT__(); \ 1047 } while (0) 1048 1049 /*MC 1050 PetscFunctionBeginUser - First executable line of user provided PETSc routine 1051 1052 Synopsis: 1053 #include <petscsys.h> 1054 void PetscFunctionBeginUser; 1055 1056 Not Collective 1057 1058 Usage: 1059 .vb 1060 int something; 1061 1062 PetscFunctionBeginUser; 1063 .ve 1064 1065 Notes: 1066 Final line of PETSc functions should be PetscFunctionReturn(0) except for main(). 1067 1068 Not available in Fortran 1069 1070 This is identical to PetscFunctionBegin except it labels the routine as a user 1071 routine instead of as a PETSc library routine. 1072 1073 Level: intermediate 1074 1075 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot` 1076 1077 M*/ 1078 #define PetscFunctionBeginUser do { \ 1079 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,2,PETSC_FALSE); \ 1080 PetscRegister__FUNCT__(); \ 1081 } while (0) 1082 1083 #define PetscStackPush(n) do { \ 1084 PetscStackPushNoCheck(n,0,PETSC_FALSE); \ 1085 CHKMEMQ; \ 1086 } while (0) 1087 1088 #define PetscStackPop do { \ 1089 CHKMEMQ; \ 1090 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1091 } while (0) 1092 1093 /*MC 1094 PetscFunctionReturn - Last executable line of each PETSc function 1095 used for error handling. Replaces return() 1096 1097 Synopsis: 1098 #include <petscsys.h> 1099 void PetscFunctionReturn(0); 1100 1101 Not Collective 1102 1103 Usage: 1104 .vb 1105 .... 1106 PetscFunctionReturn(0); 1107 } 1108 .ve 1109 1110 Notes: 1111 Not available in Fortran 1112 1113 Level: developer 1114 1115 .seealso: `PetscFunctionBegin()` 1116 1117 M*/ 1118 #define PetscFunctionReturn(a) do { \ 1119 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1120 return a; \ 1121 } while (0) 1122 1123 #define PetscFunctionReturnVoid() do { \ 1124 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1125 return; \ 1126 } while (0) 1127 #else /* PETSC_USE_DEBUG */ 1128 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 1129 #define PetscStackPopNoCheck 1130 #define PetscStackClearTop 1131 #define PetscFunctionBegin 1132 #define PetscFunctionBeginUser 1133 #define PetscFunctionBeginHot 1134 #define PetscFunctionReturn(a) return a 1135 #define PetscFunctionReturnVoid() return 1136 #define PetscStackPop CHKMEMQ 1137 #define PetscStackPush(f) CHKMEMQ 1138 #endif /* PETSC_USE_DEBUG */ 1139 1140 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1141 #define PetscStackCall(name,routine) 1142 #define PetscStackCallStandard(func,...) 1143 #else 1144 /* 1145 PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack. 1146 1147 Input Parameters: 1148 + name - string that gives the name of the function being called 1149 - routine - actual call to the routine, including ierr = and PetscCall(ierr); 1150 1151 Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes 1152 1153 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. 1154 1155 */ 1156 #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while (0) 1157 1158 /* 1159 PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack. 1160 1161 Input Parameters: 1162 + func- name of the routine 1163 - args - arguments to the routine surrounded by () 1164 1165 Notes: 1166 This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not. 1167 1168 Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1169 1170 */ 1171 #define PetscStackCallStandard(func,...) do { \ 1172 PetscStackPush(PetscStringize(func)); \ 1173 PetscErrorCode __ierr = func(__VA_ARGS__); \ 1174 PetscStackPop; \ 1175 PetscCheck(!__ierr,PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",PetscStringize(func),__ierr); \ 1176 } while (0) 1177 #endif /* PETSC_CLANG_STATIC_ANALYZER */ 1178 1179 #endif 1180