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_RETURN 99 /* PetscError() incorrectly returned an error code of 0 */ 72 #define PETSC_ERR_MAX_VALUE 100 /* this is always the one more than the largest error code */ 73 74 #define SETERRQ1(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 75 #define SETERRQ2(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 76 #define SETERRQ3(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 77 #define SETERRQ4(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 78 #define SETERRQ5(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 79 #define SETERRQ6(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 80 #define SETERRQ7(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 81 #define SETERRQ8(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 82 #define SETERRQ9(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__) 83 84 /*MC 85 SETERRQ - Macro to be called when an error has been detected, 86 87 Synopsis: 88 #include <petscsys.h> 89 PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 90 91 Collective 92 93 Input Parameters: 94 + comm - A communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error 95 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 96 - message - error message 97 98 Level: beginner 99 100 Notes: 101 This is rarely needed, one should use `PetscCheck()` and `PetscCall()` and friends to automatically handle error conditions. 102 Once the error handler is called the calling function is then returned from with the given error code. 103 104 Experienced users can set the error handler with `PetscPushErrorHandler()`. 105 106 Fortran Notes: 107 SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the 108 Fortran main program. 109 110 .seealso: `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, 111 `PetscError()`, `PetscCall()`, `CHKMEMQ`, `CHKERRA()`, `PetscCallMPI()` 112 M*/ 113 #define SETERRQ(comm, ierr, ...) \ 114 do { \ 115 PetscErrorCode ierr_seterrq_petsc_ = PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \ 116 return ierr_seterrq_petsc_ ? ierr_seterrq_petsc_ : PETSC_ERR_RETURN; \ 117 } while (0) 118 119 /* 120 Returned from PETSc functions that are called from MPI, such as related to attributes 121 Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as 122 an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call. 123 */ 124 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS; 125 PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE; 126 127 /*MC 128 SETERRMPI - Macro to be called when an error has been detected within an MPI callback function 129 130 Synopsis: 131 #include <petscsys.h> 132 PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 133 134 Collective 135 136 Input Parameters: 137 + comm - A communicator, use `PETSC_COMM_SELF` unless you know all ranks of another communicator will detect the error 138 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 139 - message - error message 140 141 Level: developer 142 143 Notes: 144 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` 145 which is registered with `MPI_Add_error_code()` when PETSc is initialized. 146 147 .seealso: `SETERRQ()`, `PetscCall()`, `PetscCallMPI()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 148 M*/ 149 #define SETERRMPI(comm, ierr, ...) return (PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__), PETSC_MPI_ERROR_CODE) 150 151 /*MC 152 SETERRA - Fortran-only macro that can be called when an error has been detected from the main program 153 154 Synopsis: 155 #include <petscsys.h> 156 PetscErrorCode SETERRA(MPI_Comm comm,PetscErrorCode ierr,char *message) 157 158 Collective 159 160 Input Parameters: 161 + comm - A communicator, so that the error can be collective 162 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 163 - message - error message in the printf format 164 165 Level: beginner 166 167 Notes: 168 This should only be used with Fortran. With C/C++, use `SETERRQ()`. 169 170 Fortran Notes: 171 `SETERRQ()` may be called from Fortran subroutines but `SETERRA()` must be called from the 172 Fortran main program. 173 174 .seealso: `SETERRQ()`, `SETERRABORT()`, `PetscCall()`, `CHKERRA()`, `PetscCallAbort()` 175 M*/ 176 177 /*MC 178 SETERRABORT - Macro that can be called when an error has been detected, 179 180 Synopsis: 181 #include <petscsys.h> 182 PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message,...) 183 184 Collective 185 186 Input Parameters: 187 + comm - A communicator, so that the error can be collective 188 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 189 - message - error message in the printf format 190 191 Level: beginner 192 193 Notes: 194 This function just calls `MPI_Abort()`. 195 196 This should only be called in routines that cannot return an error code, such as in C++ constructors. 197 198 .seealso: `SETERRQ()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `PetscCall()`, `CHKMEMQ` 199 M*/ 200 #define SETERRABORT(comm, ierr, ...) \ 201 do { \ 202 PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr, PETSC_ERROR_INITIAL, __VA_ARGS__); \ 203 MPI_Abort(comm, ierr); \ 204 } while (0) 205 206 /*MC 207 PetscCheck - Check that a particular condition is true 208 209 Synopsis: 210 #include <petscerror.h> 211 void PetscCheck(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 212 213 Collective 214 215 Input Parameters: 216 + cond - The boolean condition 217 . comm - The communicator on which the check can be collective on 218 . ierr - A nonzero error code, see include/petscerror.h for the complete list 219 - message - Error message in printf format 220 221 Notes: 222 Enabled in both optimized and debug builds. 223 224 Calls `SETERRQ()` if the assertion fails, so can only be called from functions returning a 225 `PetscErrorCode` (or equivalent type after conversion). 226 227 Level: beginner 228 229 .seealso: `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheckAbort()` 230 M*/ 231 #define PetscCheck(cond, comm, ierr, ...) \ 232 do { \ 233 if (PetscUnlikely(!(cond))) SETERRQ(comm, ierr, __VA_ARGS__); \ 234 } while (0) 235 236 /*MC 237 PetscCheckAbort - Check that a particular condition is true, otherwise prints error and aborts 238 239 Synopsis: 240 #include <petscerror.h> 241 void PetscCheckAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 242 243 Collective 244 245 Input Parameters: 246 + cond - The boolean condition 247 . comm - The communicator on which the check can be collective on 248 . ierr - A nonzero error code, see include/petscerror.h for the complete list 249 - message - Error message in printf format 250 251 Notes: 252 Enabled in both optimized and debug builds. 253 254 Calls `SETERRABORT()` if the assertion fails, can be called from a function that does not return an 255 error code, such as a C++ constructor. usually `PetscCheck()` should be used. 256 257 Level: developer 258 259 .seealso: `PetscAssertAbort()`, `PetscAssert()`, `SETERRQ()`, `PetscError()`, `PetscCall()`, `PetscCheck()`, `SETTERRABORT()` 260 M*/ 261 #define PetscCheckAbort(cond, comm, ierr, ...) \ 262 do { \ 263 if (PetscUnlikely(!(cond))) SETERRABORT(comm, ierr, __VA_ARGS__); \ 264 } while (0); 265 266 /*MC 267 PetscAssert - Assert that a particular condition is true 268 269 Synopsis: 270 #include <petscerror.h> 271 void PetscAssert(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 272 273 Collective 274 275 Input Parameters: 276 + cond - The boolean condition 277 . comm - The communicator on which the check can be collective on 278 . ierr - A nonzero error code, see include/petscerror.h for the complete list 279 - message - Error message in printf format 280 281 Notes: 282 Enabled only in debug builds. Note that any arguments to this macros are still visible to the 283 compiler optimized builds (so must still contain valid code) but are guaranteed to not be 284 executed. 285 286 See `PetscCheck()` for usage and behaviour. 287 288 This is needed instead of simply using `assert()` because this correctly handles the collective nature of errors under MPI 289 290 Level: beginner 291 292 .seealso: `PetscCheck()`, `SETERRQ()`, `PetscError()`, `PetscAssertAbort()` 293 M*/ 294 #define PetscAssert(cond, comm, ierr, ...) \ 295 do { \ 296 if (PetscUnlikelyDebug(!(cond))) SETERRQ(comm, ierr, __VA_ARGS__); \ 297 } while (0) 298 299 /*MC 300 PetscAssertAbort - Assert that a particular condition is true, otherwise prints error and aborts 301 302 Synopsis: 303 #include <petscerror.h> 304 void PetscAssertAbort(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...) 305 306 Collective 307 308 Input Parameters: 309 + cond - The boolean condition 310 . comm - The communicator on which the check can be collective on 311 . ierr - A nonzero error code, see include/petscerror.h for the complete list 312 - message - Error message in printf format 313 314 Notes: 315 Enabled only in debug builds. See `PetscCheckAbort()` for usage. 316 317 Level: beginner 318 319 .seealso: `PetscCheckAbort()`, `PetscAssert()`, `PetscCheck()`, `SETERRABORT()`, `PetscError()` 320 M*/ 321 #define PetscAssertAbort(cond, comm, ierr, ...) \ 322 do { \ 323 if (PetscUnlikelyDebug(!(cond))) SETERRABORT(comm, ierr, __VA_ARGS__); \ 324 } while (0) 325 326 /*MC 327 PetscCall - Calls a PETSc function and then checks the resulting error code, if it is non-zero it calls the error 328 handler and returns from the current function with the error code. 329 330 Synopsis: 331 #include <petscerror.h> 332 void PetscCall(PetscFunction(args)) 333 334 Not Collective 335 336 Input Parameter: 337 . PetscFunction - any PETSc function that returns an error code 338 339 Notes: 340 Once the error handler is called the calling function is then returned from with the given 341 error code. Experienced users can set the error handler with `PetscPushErrorHandler()`. 342 343 `PetscCall()` cannot be used in functions returning a datatype not convertible to 344 `PetscErrorCode`. For example, `PetscCall()` may not be used in functions returning void, use 345 `PetscCallVoid()` in this case. 346 347 Example Usage: 348 .vb 349 PetscCall(PetscInitiailize(...)); // OK to call even when PETSc is not yet initialized! 350 351 struct my_struct 352 { 353 void *data; 354 } my_complex_type; 355 356 struct my_struct bar(void) 357 { 358 PetscCall(foo(15)); // ERROR PetscErrorCode not convertible to struct my_struct! 359 } 360 361 PetscCall(bar()) // ERROR input not convertible to PetscErrorCode 362 .ve 363 364 It is also possible to call this directly on a `PetscErrorCode` variable 365 .vb 366 PetscCall(ierr); // check if ierr is nonzero 367 .ve 368 369 Should not be used to call callback functions provided by users, `PetscCallBack()` should be used in that situation. 370 371 `PetscUseTypeMethod()` or `PetscTryTypeMethod()` should be used when calling functions pointers contained in a PETSc object's `ops` array 372 373 Fortran Notes: 374 The Fortran function from which this is used must declare a variable PetscErrorCode ierr and ierr must be 375 the final argument to the PETSc function being called. 376 377 In the main program and in Fortran subroutines that do not have ierr as the final return parameter one 378 should use `PetscCallA()` 379 380 Example Fortran Usage: 381 .vb 382 PetscErrorCode ierr 383 Vec v 384 385 ... 386 PetscCall(VecShift(v,1.0,ierr)) 387 PetscCallA(VecShift(v,1.0,ierr)) 388 .ve 389 390 Level: beginner 391 392 .seealso: `SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()` 393 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCallBack()` 394 M*/ 395 396 /*MC 397 PetscCallBack - Calls a user provided PETSc callback function and then checks the resulting error code, if it is non-zero it calls the error 398 handler and returns from the current function with the error code. 399 400 Synopsis: 401 #include <petscerror.h> 402 void PetscCallBack(const char *functionname,PetscFunction(args)) 403 404 Not Collective 405 406 Input Parameters: 407 + functionname - the name of the function being called, this can be a string with spaces that describes the meaning of the callback 408 - PetscFunction - user provided callback function that returns an error code 409 410 Notes: 411 Once the error handler is called the calling function is then returned from with the given 412 error code. Experienced users can set the error handler with `PetscPushErrorHandler()`. 413 414 `PetscCallBack()` should only be called in PETSc when a call is being made to a user provided call-back routine. 415 416 Example Usage: 417 .vb 418 PetscCallBack("XXX callback to do something",a->callback(...)); 419 .ve 420 421 Level: developer 422 423 .seealso: `SETERRQ()`, `PetscCheck()`, `PetscCall()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()` 424 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCall()` 425 M*/ 426 427 #if defined(PETSC_CLANG_STATIC_ANALYZER) 428 void PetscCall(PetscErrorCode); 429 void PetscCallBack(const char *, PetscErrorCode); 430 void PetscCallVoid(PetscErrorCode); 431 #else 432 #define PetscCall(...) \ 433 do { \ 434 PetscErrorCode ierr_q_; \ 435 PetscStackUpdateLine; \ 436 ierr_q_ = __VA_ARGS__; \ 437 if (PetscUnlikely(ierr_q_)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_q_, PETSC_ERROR_REPEAT, " "); \ 438 } while (0) 439 #define PetscCallBack(function, ...) \ 440 do { \ 441 PetscErrorCode ierr_q_; \ 442 PetscStackUpdateLine; \ 443 PetscStackPushExternal(function); \ 444 ierr_q_ = __VA_ARGS__; \ 445 PetscStackPop; \ 446 if (PetscUnlikely(ierr_q_)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_q_, PETSC_ERROR_REPEAT, " "); \ 447 } while (0) 448 #define PetscCallVoid(...) \ 449 do { \ 450 PetscErrorCode ierr_void_; \ 451 PetscStackUpdateLine; \ 452 ierr_void_ = __VA_ARGS__; \ 453 if (PetscUnlikely(ierr_void_)) { \ 454 (void)PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_void_, PETSC_ERROR_REPEAT, " "); \ 455 return; \ 456 } \ 457 } while (0) 458 #endif 459 460 /*MC 461 CHKERRQ - Checks error code returned from PETSc function 462 463 Synopsis: 464 #include <petscsys.h> 465 void CHKERRQ(PetscErrorCode ierr) 466 467 Not Collective 468 469 Input Parameters: 470 . ierr - nonzero error code 471 472 Notes: 473 Deprecated in favor of `PetscCall()`. This routine behaves identically to it. 474 475 Level: deprecated 476 477 .seealso: `PetscCall()` 478 M*/ 479 #define CHKERRQ(...) PetscCall(__VA_ARGS__) 480 #define CHKERRV(...) PetscCallVoid(__VA_ARGS__) 481 482 PETSC_EXTERN void PetscMPIErrorString(PetscMPIInt, char *); 483 484 /*MC 485 PetscCallMPI - Checks error code returned from MPI calls, if non-zero it calls the error 486 handler and then returns 487 488 Synopsis: 489 #include <petscerror.h> 490 void PetscCallMPI(MPI_Function(args)) 491 492 Not Collective 493 494 Input Parameters: 495 . MPI_Function - an MPI function that returns an MPI error code 496 497 Notes: 498 Always returns the error code `PETSC_ERR_MPI`; the MPI error code and string are embedded in 499 the string error message. Do not use this to call any other routines (for example PETSc 500 routines), it should only be used for direct MPI calls. Due to limitations of the 501 preprocessor this can unfortunately not easily be enforced, so the user should take care to 502 check this themselves. 503 504 Example Usage: 505 .vb 506 PetscCallMPI(MPI_Comm_size(...)); // OK, calling MPI function 507 508 PetscCallMPI(PetscFunction(...)); // ERROR, use PetscCall() instead! 509 .ve 510 511 Fortran Notes: 512 The Fortran function from which this is used must declare a variable `PetscErrorCode` ierr and ierr must be 513 the final argument to the MPI function being called. 514 515 In the main program and in Fortran subroutines that do not have ierr as the final return parameter one 516 should use `PetscCallMPIA()` 517 518 Fortran Usage: 519 .vb 520 PetscErrorCode ierr or integer ierr 521 ... 522 PetscCallMPI(MPI_Comm_size(...,ierr)) 523 PetscCallMPIA(MPI_Comm_size(...,ierr)) ! Will abort after calling error handler 524 525 PetscCallMPI(MPI_Comm_size(...,eflag)) ! ERROR, final argument must be ierr 526 .ve 527 528 Level: beginner 529 530 .seealso: `SETERRMPI()`, `PetscCall()`, `SETERRQ()`, `SETERRABORT()`, `PetscCallAbort()`, 531 `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 532 M*/ 533 #if defined(PETSC_CLANG_STATIC_ANALYZER) 534 void PetscCallMPI(PetscMPIInt); 535 #else 536 #define PetscCallMPI(...) \ 537 do { \ 538 PetscMPIInt _7_errorcode; \ 539 char _7_errorstring[2 * MPI_MAX_ERROR_STRING]; \ 540 PetscStackUpdateLine; \ 541 PetscStackPushExternal("MPI function"); \ 542 { _7_errorcode = __VA_ARGS__; } \ 543 PetscStackPop; \ 544 if (PetscUnlikely(_7_errorcode)) { \ 545 PetscMPIErrorString(_7_errorcode, (char *)_7_errorstring); \ 546 SETERRQ(PETSC_COMM_SELF, PETSC_ERR_MPI, "MPI error %d %s", (int)_7_errorcode, _7_errorstring); \ 547 } \ 548 } while (0) 549 #endif 550 551 /*MC 552 CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error 553 handler and then returns 554 555 Synopsis: 556 #include <petscerror.h> 557 void CHKERRMPI(PetscErrorCode ierr) 558 559 Not Collective 560 561 Input Parameter: 562 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 563 564 Notes: 565 Deprecated in favor of `PetscCallMPI()`. This routine behaves identically to it. 566 567 Level: deprecated 568 569 .seealso: `PetscCallMPI()` 570 M*/ 571 #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__) 572 573 /*MC 574 PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately 575 576 Synopsis: 577 #include <petscerror.h> 578 void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr) 579 580 Collective on comm 581 582 Input Parameters: 583 + comm - the MPI communicator on which to abort 584 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 585 586 Notes: 587 This macro has identical type and usage semantics to `PetscCall()` with the important caveat 588 that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler 589 and then immediately calls `MPI_Abort()`. It can therefore be used anywhere. 590 591 As per `MPI_Abort()` semantics the communicator passed must be valid, although there is currently 592 no attempt made at handling any potential errors from `MPI_Abort()`. Note that while 593 `MPI_Abort()` is required to terminate only those processes which reside on comm, it is often 594 the case that `MPI_Abort()` terminates *all* processes. 595 596 Example Usage: 597 .vb 598 PetscErrorCode boom(void) { return PETSC_ERR_MEM; } 599 600 void foo(void) 601 { 602 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 603 } 604 605 double bar(void) 606 { 607 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 608 } 609 610 PetscCallAbort(MPI_COMM_NULL,boom()); // ERROR, communicator should be valid 611 612 struct baz 613 { 614 baz() 615 { 616 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK 617 } 618 619 ~baz() 620 { 621 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK (in fact the only way to handle PETSc errors) 622 } 623 }; 624 .ve 625 626 Level: intermediate 627 628 .seealso: `SETERRABORT()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, 629 `SETERRQ()`, `CHKMEMQ`, `PetscCallMPI()` 630 M*/ 631 #if defined(PETSC_CLANG_STATIC_ANALYZER) 632 void PetscCallAbort(MPI_Comm, PetscErrorCode); 633 void PetscCallContinue(PetscErrorCode); 634 #else 635 #define PetscCallAbort(comm, ...) \ 636 do { \ 637 PetscErrorCode ierr_abort_ = __VA_ARGS__; \ 638 if (PetscUnlikely(ierr_abort_)) { \ 639 PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_abort_, PETSC_ERROR_REPEAT, " "); \ 640 MPI_Abort(comm, ierr_abort_); \ 641 } \ 642 } while (0) 643 #define PetscCallContinue(...) \ 644 do { \ 645 PetscErrorCode ierr_continue_ = __VA_ARGS__; \ 646 if (PetscUnlikely(ierr_continue_)) PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_continue_, PETSC_ERROR_REPEAT, " "); \ 647 } while (0) 648 #endif 649 650 /*MC 651 CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately. 652 653 Synopsis: 654 #include <petscerror.h> 655 void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr) 656 657 Not Collective 658 659 Input Parameters: 660 + comm - the MPI communicator 661 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 662 663 Notes: 664 Deprecated in favor of `PetscCallAbort()`. This routine behaves identically to it. 665 666 Level: deprecated 667 668 .seealso: `PetscCallAbort()` 669 M*/ 670 #define CHKERRABORT(comm, ...) PetscCallAbort(comm, __VA_ARGS__) 671 #define CHKERRCONTINUE(...) PetscCallContinue(__VA_ARGS__) 672 673 /*MC 674 CHKERRA - Fortran-only replacement for use of `CHKERRQ()` in the main program, which aborts immediately 675 676 Synopsis: 677 #include <petscsys.h> 678 PetscErrorCode CHKERRA(PetscErrorCode ierr) 679 680 Not Collective 681 682 Input Parameters: 683 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 684 685 Level: deprecated 686 687 Note: 688 This macro is rarely needed, normal usage is `PetscCallA()` in the main Fortran program. 689 690 .seealso: `PetscCall()`, `PetscCallA()`, `PetscCallAbort()`, `CHKERRQ()`, `SETERRA()`, `SETERRQ()`, `SETERRABORT()` 691 M*/ 692 693 PETSC_EXTERN PetscBool petscwaitonerrorflg; 694 PETSC_EXTERN PetscBool petscindebugger; 695 696 /*MC 697 PETSCABORT - Call MPI_Abort with an informative error code 698 699 Synopsis: 700 #include <petscsys.h> 701 PETSCABORT(MPI_Comm comm, PetscErrorCode ierr) 702 703 Collective 704 705 Input Parameters: 706 + comm - A communicator, so that the error can be collective 707 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 708 709 Level: advanced 710 711 Notes: 712 If the option -start_in_debugger was used then this calls abort() to stop the program in the debugger. 713 714 if `PetscCIEnabledPortableErrorOutput` is set it strives to exit cleanly without call `MPI_Abort()` 715 716 M*/ 717 #define PETSCABORT(comm, ...) \ 718 do { \ 719 if (petscwaitonerrorflg) PetscSleep(1000); \ 720 if (petscindebugger) abort(); \ 721 else { \ 722 PetscErrorCode ierr_petsc_abort_ = __VA_ARGS__; \ 723 PetscMPIInt size; \ 724 MPI_Comm_size(comm, &size); \ 725 if (PetscCIEnabledPortableErrorOutput && size == PetscGlobalSize && ierr_petsc_abort_ != PETSC_ERR_SIG) { \ 726 MPI_Finalize(); \ 727 exit(0); \ 728 } else if (PetscCIEnabledPortableErrorOutput && PetscGlobalSize == 1) { \ 729 exit(0); \ 730 } else { \ 731 MPI_Abort(comm, (PetscMPIInt)ierr_petsc_abort_); \ 732 } \ 733 } \ 734 } while (0) 735 736 #ifdef PETSC_CLANGUAGE_CXX 737 /*MC 738 PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws 739 an exception 740 741 Synopsis: 742 #include <petscerror.h> 743 void PetscCallThrow(PetscErrorCode ierr) 744 745 Not Collective 746 747 Input Parameter: 748 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 749 750 Notes: 751 Requires PETSc to be configured with clanguage = c++. Throws a std::runtime_error() on error. 752 753 Once the error handler throws the exception you can use `PetscCallVoid()` which returns without 754 an error code (bad idea since the error is ignored) or `PetscCallAbort()` to have `MPI_Abort()` 755 called immediately. 756 757 Level: beginner 758 759 .seealso: `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`, 760 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 761 M*/ 762 #define PetscCallThrow(...) \ 763 do { \ 764 PetscErrorCode ierr_cxx_ = __VA_ARGS__; \ 765 if (PetscUnlikely(ierr_cxx_)) PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_cxx_, PETSC_ERROR_IN_CXX, PETSC_NULLPTR); \ 766 } while (0) 767 768 /*MC 769 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception 770 771 Synopsis: 772 #include <petscerror.h> 773 void CHKERRXX(PetscErrorCode ierr) 774 775 Not Collective 776 777 Input Parameter: 778 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 779 780 Notes: 781 Deprecated in favor of `PetscCallThrow()`. This routine behaves identically to it. 782 783 Level: deprecated 784 785 .seealso: `PetscCallThrow()` 786 M*/ 787 #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__) 788 #endif 789 790 /*MC 791 PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then 792 return a PETSc error code 793 794 Synopsis: 795 #include <petscerror.h> 796 void PetscCallCXX(expr) noexcept; 797 798 Not Collective 799 800 Input Parameter: 801 . expr - An arbitrary expression 802 803 Notes: 804 PetscCallCXX(expr) is a macro replacement for 805 .vb 806 try { 807 expr; 808 } catch (const std::exception& e) { 809 return ConvertToPetscErrorCode(e); 810 } 811 .ve 812 Due to the fact that it catches any (reasonable) exception, it is essentially noexcept. 813 814 Example Usage: 815 .vb 816 void foo(void) { throw std::runtime_error("error"); } 817 818 void bar() 819 { 820 PetscCallCXX(foo()); // ERROR bar() does not return PetscErrorCode 821 } 822 823 PetscErrorCode baz() 824 { 825 PetscCallCXX(foo()); // OK 826 827 PetscCallCXX( 828 bar(); 829 foo(); // OK mutliple statements allowed 830 ); 831 } 832 833 struct bop 834 { 835 bop() 836 { 837 PetscCallCXX(foo()); // ERROR returns PetscErrorCode, cannot be used in constructors 838 } 839 }; 840 841 // ERROR contains do-while, cannot be used as function-try block 842 PetscErrorCode qux() PetscCallCXX( 843 bar(); 844 baz(); 845 foo(); 846 return 0; 847 ) 848 .ve 849 850 Level: beginner 851 852 .seealso: `PetscCallThrow()`, `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, 853 `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 854 M*/ 855 #define PetscCallCXX(...) \ 856 do { \ 857 PetscStackUpdateLine; \ 858 try { \ 859 __VA_ARGS__; \ 860 } catch (const std::exception &e) { SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "%s", e.what()); } \ 861 } while (0) 862 863 /*MC 864 CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then 865 return a PETSc error code 866 867 Synopsis: 868 #include <petscerror.h> 869 void CHKERRCXX(func) noexcept; 870 871 Not Collective 872 873 Input Parameter: 874 . func - C++ function calls 875 876 Notes: 877 Deprecated in favor of `PetscCallCXX()`. This routine behaves identically to it. 878 879 Level: deprecated 880 881 .seealso: `PetscCallCXX()` 882 M*/ 883 #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__) 884 885 /*MC 886 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 887 888 Synopsis: 889 #include <petscsys.h> 890 CHKMEMQ; 891 892 Not Collective 893 894 Level: beginner 895 896 Notes: 897 We highly recommend using Valgrind https://petsc.org/release/faq/#valgrind or for NVIDIA CUDA systems 898 https://docs.nvidia.com/cuda/cuda-memcheck/index.html for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that 899 do not have valgrind, but is not as good as valgrind or cuda-memcheck. 900 901 Must run with the option -malloc_debug (-malloc_test in debug mode; or if `PetscMallocSetDebug()` called) to enable this option 902 903 Once the error handler is called the calling function is then returned from with the given error code. 904 905 By defaults prints location where memory that is corrupted was allocated. 906 907 Use `CHKMEMA` for functions that return void 908 909 .seealso: `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `SETERRQ()`, `PetscMallocValidate()` 910 M*/ 911 #if defined(PETSC_CLANG_STATIC_ANALYZER) 912 #define CHKMEMQ 913 #define CHKMEMA 914 #else 915 #define CHKMEMQ \ 916 do { \ 917 PetscErrorCode ierr_memq_ = PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__); \ 918 if (PetscUnlikely(ierr_memq_)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_memq_, PETSC_ERROR_REPEAT, " "); \ 919 } while (0) 920 #define CHKMEMA PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__) 921 #endif 922 923 /*E 924 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 925 926 Level: advanced 927 928 `PETSC_ERROR_IN_CXX` indicates the error was detected in C++ and an exception should be generated 929 930 Developer Notes: 931 This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 932 933 .seealso: `PetscError()`, `SETERRQ()` 934 E*/ 935 typedef enum { 936 PETSC_ERROR_INITIAL = 0, 937 PETSC_ERROR_REPEAT = 1, 938 PETSC_ERROR_IN_CXX = 2 939 } PetscErrorType; 940 941 #if defined(__clang_analyzer__) 942 __attribute__((analyzer_noreturn)) 943 #endif 944 PETSC_EXTERN PetscErrorCode 945 PetscError(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, ...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7, 8); 946 947 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 948 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int, const char *[], char **); 949 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 950 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 951 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 952 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 953 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 954 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 955 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 956 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *), void *); 957 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 958 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int, void *); 959 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int, void *), void *); 960 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 961 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 962 PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void); 963 PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") static inline void PetscSignalSegvCheckPointer(void) { 964 PetscSignalSegvCheckPointerOrMpi(); 965 } 966 967 /*MC 968 PetscErrorPrintf - Prints error messages. 969 970 Synopsis: 971 #include <petscsys.h> 972 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 973 974 Not Collective 975 976 Input Parameter: 977 . format - the usual printf() format string 978 979 Options Database Keys: 980 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 981 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 982 983 Notes: 984 Use 985 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 986 $ error is handled.) and 987 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 988 989 Use 990 `PETSC_STDERR` = FILE* obtained from a file open etc. to have stderr printed to the file. 991 `PETSC_STDOUT` = FILE* obtained from a file open etc. to have stdout printed to the file. 992 993 Use 994 `PetscPushErrorHandler()` to provide your own error handler that determines what kind of messages to print 995 996 Level: developer 997 998 Fortran Note: 999 This routine is not supported in Fortran. 1000 1001 .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscHelpPrintf()`, `PetscPrintf()`, `PetscPushErrorHandler()`, `PetscVFPrintf()`, `PetscHelpPrintf()` 1002 M*/ 1003 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2); 1004 1005 /*E 1006 PetscFPTrap - types of floating point exceptions that may be trapped 1007 1008 Currently only `PETSC_FP_TRAP_OFF` and `PETSC_FP_TRAP_ON` are handled. All others are treated as `PETSC_FP_TRAP_ON`. 1009 1010 Level: intermediate 1011 1012 .seealso: `PetscSetFPTrap()`, `PetscPushFPTrap()` 1013 E*/ 1014 typedef enum { 1015 PETSC_FP_TRAP_OFF = 0, 1016 PETSC_FP_TRAP_INDIV = 1, 1017 PETSC_FP_TRAP_FLTOPERR = 2, 1018 PETSC_FP_TRAP_FLTOVF = 4, 1019 PETSC_FP_TRAP_FLTUND = 8, 1020 PETSC_FP_TRAP_FLTDIV = 16, 1021 PETSC_FP_TRAP_FLTINEX = 32 1022 } PetscFPTrap; 1023 #define PETSC_FP_TRAP_ON (PetscFPTrap)(PETSC_FP_TRAP_INDIV | PETSC_FP_TRAP_FLTOPERR | PETSC_FP_TRAP_FLTOVF | PETSC_FP_TRAP_FLTDIV | PETSC_FP_TRAP_FLTINEX) 1024 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 1025 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 1026 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 1027 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void); 1028 1029 /* 1030 Allows the code to build a stack frame as it runs 1031 */ 1032 1033 #if defined(PETSC_USE_DEBUG) 1034 #define PETSCSTACKSIZE 64 1035 typedef struct { 1036 const char *function[PETSCSTACKSIZE]; 1037 const char *file[PETSCSTACKSIZE]; 1038 int line[PETSCSTACKSIZE]; 1039 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */ 1040 int currentsize; 1041 int hotdepth; 1042 PetscBool check; /* option to check for correct Push/Pop semantics, true for default petscstack but not other stacks */ 1043 } PetscStack; 1044 PETSC_EXTERN PetscStack petscstack; 1045 #else 1046 typedef struct { 1047 char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp; 1048 } PetscStack; 1049 #endif 1050 1051 #if defined(PETSC_SERIALIZE_FUNCTIONS) 1052 #include <petsc/private/petscfptimpl.h> 1053 /* 1054 Registers the current function into the global function pointer to function name table 1055 1056 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 1057 */ 1058 #define PetscRegister__FUNCT__() \ 1059 do { \ 1060 static PetscBool __chked = PETSC_FALSE; \ 1061 if (!__chked) { \ 1062 void *ptr; \ 1063 PetscDLSym(NULL, PETSC_FUNCTION_NAME, &ptr); \ 1064 __chked = PETSC_TRUE; \ 1065 } \ 1066 } while (0) 1067 #else 1068 #define PetscRegister__FUNCT__() 1069 #endif 1070 1071 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1072 #define PetscStackPushNoCheck(funct, petsc_routine, hot) 1073 #define PetscStackUpdateLine 1074 #define PetscStackPushExternal(funct) 1075 #define PetscStackPopNoCheck 1076 #define PetscStackClearTop 1077 #define PetscFunctionBegin 1078 #define PetscFunctionBeginUser 1079 #define PetscFunctionBeginHot 1080 #define PetscFunctionReturn(a) return a 1081 #define PetscFunctionReturnVoid() return 1082 #define PetscStackPop 1083 #define PetscStackPush(f) 1084 #elif defined(PETSC_USE_DEBUG) 1085 1086 #define PetscStackPush_Private(stack__, file__, func__, line__, petsc_routine__, hot__) \ 1087 do { \ 1088 if (stack__.currentsize < PETSCSTACKSIZE) { \ 1089 stack__.function[stack__.currentsize] = func__; \ 1090 if (petsc_routine__) { \ 1091 stack__.file[stack__.currentsize] = file__; \ 1092 stack__.line[stack__.currentsize] = line__; \ 1093 } else { \ 1094 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 1095 stack__.line[stack__.currentsize] = 0; \ 1096 } \ 1097 stack__.petscroutine[stack__.currentsize] = petsc_routine__; \ 1098 } \ 1099 ++stack__.currentsize; \ 1100 stack__.hotdepth += (hot__ || stack__.hotdepth); \ 1101 } while (0) 1102 1103 /* uses PetscCheckAbort() because may be used in a function that does not return an error code */ 1104 #define PetscStackPop_Private(stack__, func__) \ 1105 do { \ 1106 PetscCheckAbort(!stack__.check || stack__.currentsize > 0, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Invalid stack size %d, pop %s %s:%d.\n", stack__.currentsize, func__, __FILE__, __LINE__); \ 1107 if (--stack__.currentsize < PETSCSTACKSIZE) { \ 1108 PetscCheckAbort(!stack__.check || stack__.petscroutine[stack__.currentsize] != 1 || stack__.function[stack__.currentsize] == (const char *)(func__), PETSC_COMM_SELF, PETSC_ERR_PLIB, "Invalid stack: push from %s %s:%d. Pop from %s %s:%d.\n", \ 1109 stack__.function[stack__.currentsize], stack__.file[stack__.currentsize], stack__.line[stack__.currentsize], func__, __FILE__, __LINE__); \ 1110 stack__.function[stack__.currentsize] = PETSC_NULLPTR; \ 1111 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 1112 stack__.line[stack__.currentsize] = 0; \ 1113 stack__.petscroutine[stack__.currentsize] = 0; \ 1114 } \ 1115 stack__.hotdepth = PetscMax(stack__.hotdepth - 1, 0); \ 1116 } while (0) 1117 1118 /*MC 1119 PetscStackPushNoCheck - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is 1120 currently in the source code. 1121 1122 Not Collective 1123 1124 Synopsis: 1125 #include <petscsys.h> 1126 void PetscStackPushNoCheck(char *funct,int petsc_routine,PetscBool hot); 1127 1128 Input Parameters: 1129 + funct - the function name 1130 . petsc_routine - 2 user function, 1 PETSc function, 0 some other function 1131 - hot - indicates that the function may be called often so expensive error checking should be turned off inside the function 1132 1133 Level: developer 1134 1135 Notes: 1136 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1137 occurred, for example, when a signal is received without running in the debugger. It is recommended to use the debugger if extensive information is needed to 1138 help debug the problem. 1139 1140 This version does not check the memory corruption (an expensive operation), use `PetscStackPush()` to check the memory. 1141 1142 Use `PetscStackPushExternal()` for a function call that is about to be made to a non-PETSc or user function (such as BLAS etc). 1143 1144 The default stack is a global variable called `petscstack`. 1145 1146 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1147 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPush()`, `PetscStackPop`, 1148 `PetscStackPushExternal()` 1149 M*/ 1150 #define PetscStackPushNoCheck(funct, petsc_routine, hot) \ 1151 do { \ 1152 PetscStackSAWsTakeAccess(); \ 1153 PetscStackPush_Private(petscstack, __FILE__, funct, __LINE__, petsc_routine, hot); \ 1154 PetscStackSAWsGrantAccess(); \ 1155 } while (0) 1156 1157 /*MC 1158 PetscStackUpdateLine - in a function that has a `PetscFunctionBegin` or `PetscFunctionBeginUser` updates the stack line number to the 1159 current line number. 1160 1161 Not Collective 1162 1163 Synopsis: 1164 #include <petscsys.h> 1165 void PetscStackUpdateLine 1166 1167 Level: developer 1168 1169 Notes: 1170 Using `PetscCall()` and friends automatically handles this process 1171 1172 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1173 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1174 help debug the problem. 1175 1176 The default stack is a global variable called petscstack. 1177 1178 This is used by `PetscCall()` and is otherwise not like to be needed 1179 1180 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`, `PetscCall()` 1181 M*/ 1182 #define PetscStackUpdateLine \ 1183 if (petscstack.currentsize > 0 && petscstack.function[petscstack.currentsize - 1] == PETSC_FUNCTION_NAME) { petscstack.line[petscstack.currentsize - 1] = __LINE__; } 1184 1185 /*MC 1186 PetscStackPushExternal - Pushes a new function name onto the PETSc default stack that tracks where the running program is 1187 currently in the source code. Does not include the filename or line number since this is called by the calling routine 1188 for non-PETSc or user functions. 1189 1190 Not Collective 1191 1192 Synopsis: 1193 #include <petscsys.h> 1194 void PetscStackPushExternal(char *funct); 1195 1196 Input Parameters: 1197 . funct - the function name 1198 1199 Level: developer 1200 1201 Notes: 1202 Using `PetscCallExternal()` and friends automatically handles this process 1203 1204 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1205 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1206 help debug the problem. 1207 1208 The default stack is a global variable called `petscstack`. 1209 1210 This is to be used when calling an external package function such as a BLAS function. 1211 1212 This also updates the stack line number for the current stack function. 1213 1214 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1215 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1216 M*/ 1217 #define PetscStackPushExternal(funct) \ 1218 do { \ 1219 PetscStackUpdateLine; \ 1220 PetscStackPushNoCheck(funct, 0, PETSC_TRUE); \ 1221 } while (0); 1222 1223 /*MC 1224 PetscStackPopNoCheck - Pops a function name from the PETSc default stack that tracks where the running program is 1225 currently in the source code. 1226 1227 Not Collective 1228 1229 Synopsis: 1230 #include <petscsys.h> 1231 void PetscStackPopNoCheck(char *funct); 1232 1233 Input Parameter: 1234 . funct - the function name 1235 1236 Level: developer 1237 1238 Notes: 1239 Using `PetscCall()`, `PetscCallExternal()`, `PetscCallBack()` and friends negates the need to call this 1240 1241 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1242 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1243 help debug the problem. 1244 1245 The default stack is a global variable called petscstack. 1246 1247 Developer Note: 1248 `PetscStackPopNoCheck()` takes a function argument while `PetscStackPop` does not, this difference is likely just historical. 1249 1250 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1251 M*/ 1252 #define PetscStackPopNoCheck(funct) \ 1253 do { \ 1254 PetscStackSAWsTakeAccess(); \ 1255 PetscStackPop_Private(petscstack, funct); \ 1256 PetscStackSAWsGrantAccess(); \ 1257 } while (0) 1258 1259 #define PetscStackClearTop \ 1260 do { \ 1261 PetscStackSAWsTakeAccess(); \ 1262 if (petscstack.currentsize > 0 && --petscstack.currentsize < PETSCSTACKSIZE) { \ 1263 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 1264 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 1265 petscstack.line[petscstack.currentsize] = 0; \ 1266 petscstack.petscroutine[petscstack.currentsize] = 0; \ 1267 } \ 1268 petscstack.hotdepth = PetscMax(petscstack.hotdepth - 1, 0); \ 1269 PetscStackSAWsGrantAccess(); \ 1270 } while (0) 1271 1272 /*MC 1273 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 1274 line of PETSc functions should be `PetscFunctionReturn`(0); 1275 1276 Synopsis: 1277 #include <petscsys.h> 1278 void PetscFunctionBegin; 1279 1280 Not Collective 1281 1282 Usage: 1283 .vb 1284 int something; 1285 1286 PetscFunctionBegin; 1287 .ve 1288 1289 Notes: 1290 Use `PetscFunctionBeginUser` for application codes. 1291 1292 Not available in Fortran 1293 1294 Level: developer 1295 1296 .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()` 1297 1298 M*/ 1299 #define PetscFunctionBegin \ 1300 do { \ 1301 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_FALSE); \ 1302 PetscRegister__FUNCT__(); \ 1303 } while (0) 1304 1305 /*MC 1306 PetscFunctionBeginHot - Substitute for `PetscFunctionBegin` to be used in functions that are called in 1307 performance-critical circumstances. Use of this function allows for lighter profiling by default. 1308 1309 Synopsis: 1310 #include <petscsys.h> 1311 void PetscFunctionBeginHot; 1312 1313 Not Collective 1314 1315 Usage: 1316 .vb 1317 int something; 1318 1319 PetscFunctionBeginHot; 1320 .ve 1321 1322 Notes: 1323 Not available in Fortran 1324 1325 Level: developer 1326 1327 .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()`, `PetscStackPushNoCheck()` 1328 1329 M*/ 1330 #define PetscFunctionBeginHot \ 1331 do { \ 1332 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_TRUE); \ 1333 PetscRegister__FUNCT__(); \ 1334 } while (0) 1335 1336 /*MC 1337 PetscFunctionBeginUser - First executable line of user provided routines 1338 1339 Synopsis: 1340 #include <petscsys.h> 1341 void PetscFunctionBeginUser; 1342 1343 Not Collective 1344 1345 Usage: 1346 .vb 1347 int something; 1348 1349 PetscFunctionBeginUser; 1350 .ve 1351 1352 Notes: 1353 Functions that incorporate this must call `PetscFunctionReturn()` instead of return except for main(). 1354 1355 May be used before `PetscInitialize()` 1356 1357 Not available in Fortran 1358 1359 This is identical to `PetscFunctionBegin` except it labels the routine as a user 1360 routine instead of as a PETSc library routine. 1361 1362 Level: intermediate 1363 1364 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot`, `PetscStackPushNoCheck()` 1365 1366 M*/ 1367 #define PetscFunctionBeginUser \ 1368 do { \ 1369 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 2, PETSC_FALSE); \ 1370 PetscRegister__FUNCT__(); \ 1371 } while (0) 1372 1373 /*MC 1374 PetscStackPush - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is 1375 currently in the source code and verifies the memory is not corrupted. 1376 1377 Not Collective 1378 1379 Synopsis: 1380 #include <petscsys.h> 1381 void PetscStackPush(char *funct) 1382 1383 Input Parameter: 1384 . funct - the function name 1385 1386 Level: developer 1387 1388 Notes: 1389 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1390 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1391 help debug the problem. 1392 1393 The default stack is a global variable called petscstack. 1394 1395 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1396 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1397 M*/ 1398 #define PetscStackPush(n) \ 1399 do { \ 1400 PetscStackPushNoCheck(n, 0, PETSC_FALSE); \ 1401 CHKMEMQ; \ 1402 } while (0) 1403 1404 /*MC 1405 PetscStackPop - Pops a function name from the PETSc default stack that tracks where the running program is 1406 currently in the source code and verifies the memory is not corrupted. 1407 1408 Not Collective 1409 1410 Synopsis: 1411 #include <petscsys.h> 1412 void PetscStackPop 1413 1414 Level: developer 1415 1416 Notes: 1417 In debug mode PETSc maintains a stack of the current function calls that can be used to help to quickly see where a problem has 1418 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1419 help debug the problem. 1420 1421 The default stack is a global variable called petscstack. 1422 1423 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPopNoCheck()`, `PetscStackPush()` 1424 M*/ 1425 #define PetscStackPop \ 1426 do { \ 1427 CHKMEMQ; \ 1428 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1429 } while (0) 1430 1431 /*MC 1432 PetscFunctionReturn - Last executable line of each PETSc function 1433 used for error handling. Replaces `return()` 1434 1435 Synopsis: 1436 #include <petscsys.h> 1437 void PetscFunctionReturn(0); 1438 1439 Not Collective 1440 1441 Usage: 1442 .vb 1443 .... 1444 PetscFunctionReturn(0); 1445 } 1446 .ve 1447 1448 Note: 1449 Not available in Fortran 1450 1451 Level: developer 1452 1453 .seealso: `PetscFunctionBegin()`, `PetscStackPopNoCheck()` 1454 1455 M*/ 1456 #define PetscFunctionReturn(a) \ 1457 do { \ 1458 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1459 return a; \ 1460 } while (0) 1461 1462 #define PetscFunctionReturnVoid() \ 1463 do { \ 1464 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1465 return; \ 1466 } while (0) 1467 #else /* PETSC_USE_DEBUG */ 1468 #define PetscStackPushNoCheck(funct, petsc_routine, hot) 1469 #define PetscStackUpdateLine 1470 #define PetscStackPushExternal(funct) 1471 #define PetscStackPopNoCheck 1472 #define PetscStackClearTop 1473 #define PetscFunctionBegin 1474 #define PetscFunctionBeginUser 1475 #define PetscFunctionBeginHot 1476 #define PetscFunctionReturn(a) return a 1477 #define PetscFunctionReturnVoid() return 1478 #define PetscStackPop CHKMEMQ 1479 #define PetscStackPush(f) CHKMEMQ 1480 #endif /* PETSC_USE_DEBUG */ 1481 1482 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1483 #define PetscStackCallExternalVoid(name, routine) 1484 #define PetscCallExternal(func, ...) 1485 #else 1486 /*MC 1487 PetscStackCallExternalVoid - Calls an external library routine or user function after pushing the name of the routine on the stack. 1488 1489 Input Parameters: 1490 + name - string that gives the name of the function being called 1491 - routine - actual call to the routine, for example, functionname(a,b) 1492 1493 Level: developer 1494 1495 Note: 1496 Often one should use `PetscCallExternal()` instead. This routine is intended for external library routines that DO NOT return error codes 1497 1498 In debug mode this also checks the memory for corruption at the end of the function call. 1499 1500 Certain external packages, such as BLAS/LAPACK may have their own macros for managing the call, error checking, etc. 1501 1502 Developer Note: 1503 This is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1504 1505 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscCallExternal()`, `PetscCallBLAS()` 1506 @*/ 1507 #define PetscStackCallExternalVoid(name, routine) \ 1508 do { \ 1509 PetscStackPush(name); \ 1510 routine; \ 1511 PetscStackPop; \ 1512 } while (0) 1513 1514 /*MC 1515 PetscCallExternal - Calls an external library routine that returns an error code after pushing the name of the routine on the stack. 1516 1517 Input Parameters: 1518 + func- name of the routine 1519 - args - arguments to the routine 1520 1521 Level: developer 1522 1523 Notes: 1524 This is intended for external package routines that return error codes. Use `PetscStackCallExternalVoid()` for those that do not. 1525 1526 In debug mode this also checks the memory for corruption at the end of the function call. 1527 1528 Assumes the error return code of the function is an integer and that a value of 0 indicates success 1529 1530 Developer Note: 1531 This is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1532 1533 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscStackCallExternalVoid()` 1534 M*/ 1535 #define PetscCallExternal(func, ...) \ 1536 do { \ 1537 PetscStackPush(PetscStringize(func)); \ 1538 PetscErrorCode __ierr = func(__VA_ARGS__); \ 1539 PetscStackPop; \ 1540 PetscCheck(!__ierr, PETSC_COMM_SELF, PETSC_ERR_LIB, "Error in %s(): error code %d", PetscStringize(func), __ierr); \ 1541 } while (0) 1542 #endif /* PETSC_CLANG_STATIC_ANALYZER */ 1543 1544 #endif 1545