1 /* 2 Contains all error handling interfaces for PETSc. 3 */ 4 #ifndef 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 { \ 543 _7_errorcode = __VA_ARGS__; \ 544 } \ 545 PetscStackPop; \ 546 if (PetscUnlikely(_7_errorcode)) { \ 547 PetscMPIErrorString(_7_errorcode, (char *)_7_errorstring); \ 548 SETERRQ(PETSC_COMM_SELF, PETSC_ERR_MPI, "MPI error %d %s", (int)_7_errorcode, _7_errorstring); \ 549 } \ 550 } while (0) 551 #endif 552 553 /*MC 554 CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error 555 handler and then returns 556 557 Synopsis: 558 #include <petscerror.h> 559 void CHKERRMPI(PetscErrorCode ierr) 560 561 Not Collective 562 563 Input Parameter: 564 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 565 566 Notes: 567 Deprecated in favor of `PetscCallMPI()`. This routine behaves identically to it. 568 569 Level: deprecated 570 571 .seealso: `PetscCallMPI()` 572 M*/ 573 #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__) 574 575 /*MC 576 PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately 577 578 Synopsis: 579 #include <petscerror.h> 580 void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr) 581 582 Collective on comm 583 584 Input Parameters: 585 + comm - the MPI communicator on which to abort 586 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 587 588 Notes: 589 This macro has identical type and usage semantics to `PetscCall()` with the important caveat 590 that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler 591 and then immediately calls `MPI_Abort()`. It can therefore be used anywhere. 592 593 As per `MPI_Abort()` semantics the communicator passed must be valid, although there is currently 594 no attempt made at handling any potential errors from `MPI_Abort()`. Note that while 595 `MPI_Abort()` is required to terminate only those processes which reside on comm, it is often 596 the case that `MPI_Abort()` terminates *all* processes. 597 598 Example Usage: 599 .vb 600 PetscErrorCode boom(void) { return PETSC_ERR_MEM; } 601 602 void foo(void) 603 { 604 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 605 } 606 607 double bar(void) 608 { 609 PetscCallAbort(PETSC_COMM_WORLD,boom()); // OK, does not return a type 610 } 611 612 PetscCallAbort(MPI_COMM_NULL,boom()); // ERROR, communicator should be valid 613 614 struct baz 615 { 616 baz() 617 { 618 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK 619 } 620 621 ~baz() 622 { 623 PetscCallAbort(PETSC_COMM_SELF,boom()); // OK (in fact the only way to handle PETSc errors) 624 } 625 }; 626 .ve 627 628 Level: intermediate 629 630 .seealso: `SETERRABORT()`, `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, 631 `SETERRQ()`, `CHKMEMQ`, `PetscCallMPI()` 632 M*/ 633 #if defined(PETSC_CLANG_STATIC_ANALYZER) 634 void PetscCallAbort(MPI_Comm, PetscErrorCode); 635 void PetscCallContinue(PetscErrorCode); 636 #else 637 #define PetscCallAbort(comm, ...) \ 638 do { \ 639 PetscErrorCode ierr_abort_ = __VA_ARGS__; \ 640 if (PetscUnlikely(ierr_abort_)) { \ 641 PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_abort_, PETSC_ERROR_REPEAT, " "); \ 642 MPI_Abort(comm, ierr_abort_); \ 643 } \ 644 } while (0) 645 #define PetscCallContinue(...) \ 646 do { \ 647 PetscErrorCode ierr_continue_ = __VA_ARGS__; \ 648 if (PetscUnlikely(ierr_continue_)) PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_continue_, PETSC_ERROR_REPEAT, " "); \ 649 } while (0) 650 #endif 651 652 /*MC 653 CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately. 654 655 Synopsis: 656 #include <petscerror.h> 657 void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr) 658 659 Not Collective 660 661 Input Parameters: 662 + comm - the MPI communicator 663 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 664 665 Notes: 666 Deprecated in favor of `PetscCallAbort()`. This routine behaves identically to it. 667 668 Level: deprecated 669 670 .seealso: `PetscCallAbort()` 671 M*/ 672 #define CHKERRABORT(comm, ...) PetscCallAbort(comm, __VA_ARGS__) 673 #define CHKERRCONTINUE(...) PetscCallContinue(__VA_ARGS__) 674 675 /*MC 676 CHKERRA - Fortran-only replacement for use of `CHKERRQ()` in the main program, which aborts immediately 677 678 Synopsis: 679 #include <petscsys.h> 680 PetscErrorCode CHKERRA(PetscErrorCode ierr) 681 682 Not Collective 683 684 Input Parameters: 685 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 686 687 Level: deprecated 688 689 Note: 690 This macro is rarely needed, normal usage is `PetscCallA()` in the main Fortran program. 691 692 .seealso: `PetscCall()`, `PetscCallA()`, `PetscCallAbort()`, `CHKERRQ()`, `SETERRA()`, `SETERRQ()`, `SETERRABORT()` 693 M*/ 694 695 PETSC_EXTERN PetscBool petscwaitonerrorflg; 696 PETSC_EXTERN PetscBool petscindebugger; 697 698 /*MC 699 PETSCABORT - Call MPI_Abort with an informative error code 700 701 Synopsis: 702 #include <petscsys.h> 703 PETSCABORT(MPI_Comm comm, PetscErrorCode ierr) 704 705 Collective 706 707 Input Parameters: 708 + comm - A communicator, so that the error can be collective 709 - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 710 711 Level: advanced 712 713 Notes: 714 If the option -start_in_debugger was used then this calls abort() to stop the program in the debugger. 715 716 if `PetscCIEnabledPortableErrorOutput` is set it strives to exit cleanly without call `MPI_Abort()` 717 718 M*/ 719 #define PETSCABORT(comm, ...) \ 720 do { \ 721 if (petscwaitonerrorflg) PetscSleep(1000); \ 722 if (petscindebugger) abort(); \ 723 else { \ 724 PetscErrorCode ierr_petsc_abort_ = __VA_ARGS__; \ 725 PetscMPIInt size; \ 726 MPI_Comm_size(comm, &size); \ 727 if (PetscCIEnabledPortableErrorOutput && size == PetscGlobalSize && ierr_petsc_abort_ != PETSC_ERR_SIG) { \ 728 MPI_Finalize(); \ 729 exit(0); \ 730 } else if (PetscCIEnabledPortableErrorOutput && PetscGlobalSize == 1) { \ 731 exit(0); \ 732 } else { \ 733 MPI_Abort(comm, (PetscMPIInt)ierr_petsc_abort_); \ 734 } \ 735 } \ 736 } while (0) 737 738 #ifdef PETSC_CLANGUAGE_CXX 739 /*MC 740 PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws 741 an exception 742 743 Synopsis: 744 #include <petscerror.h> 745 void PetscCallThrow(PetscErrorCode ierr) 746 747 Not Collective 748 749 Input Parameter: 750 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 751 752 Notes: 753 Requires PETSc to be configured with clanguage = c++. Throws a std::runtime_error() on error. 754 755 Once the error handler throws the exception you can use `PetscCallVoid()` which returns without 756 an error code (bad idea since the error is ignored) or `PetscCallAbort()` to have `MPI_Abort()` 757 called immediately. 758 759 Level: beginner 760 761 .seealso: `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, `PetscTraceBackErrorHandler()`, 762 `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 763 M*/ 764 #define PetscCallThrow(...) \ 765 do { \ 766 PetscErrorCode ierr_cxx_ = __VA_ARGS__; \ 767 if (PetscUnlikely(ierr_cxx_)) PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_cxx_, PETSC_ERROR_IN_CXX, PETSC_NULLPTR); \ 768 } while (0) 769 770 /*MC 771 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception 772 773 Synopsis: 774 #include <petscerror.h> 775 void CHKERRXX(PetscErrorCode ierr) 776 777 Not Collective 778 779 Input Parameter: 780 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 781 782 Notes: 783 Deprecated in favor of `PetscCallThrow()`. This routine behaves identically to it. 784 785 Level: deprecated 786 787 .seealso: `PetscCallThrow()` 788 M*/ 789 #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__) 790 #endif 791 792 /*MC 793 PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then 794 return a PETSc error code 795 796 Synopsis: 797 #include <petscerror.h> 798 void PetscCallCXX(expr) noexcept; 799 800 Not Collective 801 802 Input Parameter: 803 . expr - An arbitrary expression 804 805 Notes: 806 PetscCallCXX(expr) is a macro replacement for 807 .vb 808 try { 809 expr; 810 } catch (const std::exception& e) { 811 return ConvertToPetscErrorCode(e); 812 } 813 .ve 814 Due to the fact that it catches any (reasonable) exception, it is essentially noexcept. 815 816 Example Usage: 817 .vb 818 void foo(void) { throw std::runtime_error("error"); } 819 820 void bar() 821 { 822 PetscCallCXX(foo()); // ERROR bar() does not return PetscErrorCode 823 } 824 825 PetscErrorCode baz() 826 { 827 PetscCallCXX(foo()); // OK 828 829 PetscCallCXX( 830 bar(); 831 foo(); // OK mutliple statements allowed 832 ); 833 } 834 835 struct bop 836 { 837 bop() 838 { 839 PetscCallCXX(foo()); // ERROR returns PetscErrorCode, cannot be used in constructors 840 } 841 }; 842 843 // ERROR contains do-while, cannot be used as function-try block 844 PetscErrorCode qux() PetscCallCXX( 845 bar(); 846 baz(); 847 foo(); 848 return 0; 849 ) 850 .ve 851 852 Level: beginner 853 854 .seealso: `PetscCallThrow()`, `SETERRQ()`, `PetscCall()`, `SETERRABORT()`, `PetscCallAbort()`, 855 `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ` 856 M*/ 857 #define PetscCallCXX(...) \ 858 do { \ 859 PetscStackUpdateLine; \ 860 try { \ 861 __VA_ARGS__; \ 862 } catch (const std::exception &e) { \ 863 SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "%s", e.what()); \ 864 } \ 865 } while (0) 866 867 /*MC 868 CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then 869 return a PETSc error code 870 871 Synopsis: 872 #include <petscerror.h> 873 void CHKERRCXX(func) noexcept; 874 875 Not Collective 876 877 Input Parameter: 878 . func - C++ function calls 879 880 Notes: 881 Deprecated in favor of `PetscCallCXX()`. This routine behaves identically to it. 882 883 Level: deprecated 884 885 .seealso: `PetscCallCXX()` 886 M*/ 887 #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__) 888 889 /*MC 890 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 891 892 Synopsis: 893 #include <petscsys.h> 894 CHKMEMQ; 895 896 Not Collective 897 898 Level: beginner 899 900 Notes: 901 We highly recommend using Valgrind https://petsc.org/release/faq/#valgrind or for NVIDIA CUDA systems 902 https://docs.nvidia.com/cuda/cuda-memcheck/index.html for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that 903 do not have valgrind, but is not as good as valgrind or cuda-memcheck. 904 905 Must run with the option -malloc_debug (-malloc_test in debug mode; or if `PetscMallocSetDebug()` called) to enable this option 906 907 Once the error handler is called the calling function is then returned from with the given error code. 908 909 By defaults prints location where memory that is corrupted was allocated. 910 911 Use `CHKMEMA` for functions that return void 912 913 .seealso: `PetscTraceBackErrorHandler()`, `PetscPushErrorHandler()`, `PetscError()`, `SETERRQ()`, `PetscMallocValidate()` 914 M*/ 915 #if defined(PETSC_CLANG_STATIC_ANALYZER) 916 #define CHKMEMQ 917 #define CHKMEMA 918 #else 919 #define CHKMEMQ \ 920 do { \ 921 PetscErrorCode ierr_memq_ = PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__); \ 922 if (PetscUnlikely(ierr_memq_)) return PetscError(PETSC_COMM_SELF, __LINE__, PETSC_FUNCTION_NAME, __FILE__, ierr_memq_, PETSC_ERROR_REPEAT, " "); \ 923 } while (0) 924 #define CHKMEMA PetscMallocValidate(__LINE__, PETSC_FUNCTION_NAME, __FILE__) 925 #endif 926 927 /*E 928 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 929 930 Level: advanced 931 932 `PETSC_ERROR_IN_CXX` indicates the error was detected in C++ and an exception should be generated 933 934 Developer Notes: 935 This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 936 937 .seealso: `PetscError()`, `SETERRQ()` 938 E*/ 939 typedef enum { 940 PETSC_ERROR_INITIAL = 0, 941 PETSC_ERROR_REPEAT = 1, 942 PETSC_ERROR_IN_CXX = 2 943 } PetscErrorType; 944 945 #if defined(__clang_analyzer__) 946 __attribute__((analyzer_noreturn)) 947 #endif 948 PETSC_EXTERN PetscErrorCode 949 PetscError(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, ...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7, 8); 950 951 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 952 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int, const char *[], char **); 953 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 954 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 955 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 956 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 957 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 958 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 959 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *) PETSC_ATTRIBUTE_COLD; 960 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm, int, const char *, const char *, PetscErrorCode, PetscErrorType, const char *, void *), void *); 961 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 962 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int, void *); 963 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int, void *), void *); 964 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 965 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 966 PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void); 967 PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") static inline void PetscSignalSegvCheckPointer(void) 968 { 969 PetscSignalSegvCheckPointerOrMpi(); 970 } 971 972 /*MC 973 PetscErrorPrintf - Prints error messages. 974 975 Synopsis: 976 #include <petscsys.h> 977 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 978 979 Not Collective 980 981 Input Parameter: 982 . format - the usual printf() format string 983 984 Options Database Keys: 985 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 986 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 987 988 Notes: 989 Use 990 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 991 $ error is handled.) and 992 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 993 994 Use 995 `PETSC_STDERR` = FILE* obtained from a file open etc. to have stderr printed to the file. 996 `PETSC_STDOUT` = FILE* obtained from a file open etc. to have stdout printed to the file. 997 998 Use 999 `PetscPushErrorHandler()` to provide your own error handler that determines what kind of messages to print 1000 1001 Level: developer 1002 1003 Fortran Note: 1004 This routine is not supported in Fortran. 1005 1006 .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscHelpPrintf()`, `PetscPrintf()`, `PetscPushErrorHandler()`, `PetscVFPrintf()`, `PetscHelpPrintf()` 1007 M*/ 1008 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2); 1009 1010 /*E 1011 PetscFPTrap - types of floating point exceptions that may be trapped 1012 1013 Currently only `PETSC_FP_TRAP_OFF` and `PETSC_FP_TRAP_ON` are handled. All others are treated as `PETSC_FP_TRAP_ON`. 1014 1015 Level: intermediate 1016 1017 .seealso: `PetscSetFPTrap()`, `PetscPushFPTrap()` 1018 E*/ 1019 typedef enum { 1020 PETSC_FP_TRAP_OFF = 0, 1021 PETSC_FP_TRAP_INDIV = 1, 1022 PETSC_FP_TRAP_FLTOPERR = 2, 1023 PETSC_FP_TRAP_FLTOVF = 4, 1024 PETSC_FP_TRAP_FLTUND = 8, 1025 PETSC_FP_TRAP_FLTDIV = 16, 1026 PETSC_FP_TRAP_FLTINEX = 32 1027 } PetscFPTrap; 1028 #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) 1029 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 1030 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 1031 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 1032 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void); 1033 1034 /* 1035 Allows the code to build a stack frame as it runs 1036 */ 1037 1038 #if defined(PETSC_USE_DEBUG) 1039 #define PETSCSTACKSIZE 64 1040 typedef struct { 1041 const char *function[PETSCSTACKSIZE]; 1042 const char *file[PETSCSTACKSIZE]; 1043 int line[PETSCSTACKSIZE]; 1044 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */ 1045 int currentsize; 1046 int hotdepth; 1047 PetscBool check; /* option to check for correct Push/Pop semantics, true for default petscstack but not other stacks */ 1048 } PetscStack; 1049 PETSC_EXTERN PetscStack petscstack; 1050 #else 1051 typedef struct { 1052 char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp; 1053 } PetscStack; 1054 #endif 1055 1056 #if defined(PETSC_SERIALIZE_FUNCTIONS) 1057 #include <petsc/private/petscfptimpl.h> 1058 /* 1059 Registers the current function into the global function pointer to function name table 1060 1061 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 1062 */ 1063 #define PetscRegister__FUNCT__() \ 1064 do { \ 1065 static PetscBool __chked = PETSC_FALSE; \ 1066 if (!__chked) { \ 1067 void *ptr; \ 1068 PetscDLSym(NULL, PETSC_FUNCTION_NAME, &ptr); \ 1069 __chked = PETSC_TRUE; \ 1070 } \ 1071 } while (0) 1072 #else 1073 #define PetscRegister__FUNCT__() 1074 #endif 1075 1076 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1077 #define PetscStackPushNoCheck(funct, petsc_routine, hot) 1078 #define PetscStackUpdateLine 1079 #define PetscStackPushExternal(funct) 1080 #define PetscStackPopNoCheck 1081 #define PetscStackClearTop 1082 #define PetscFunctionBegin 1083 #define PetscFunctionBeginUser 1084 #define PetscFunctionBeginHot 1085 #define PetscFunctionReturn(a) return a 1086 #define PetscFunctionReturnVoid() return 1087 #define PetscStackPop 1088 #define PetscStackPush(f) 1089 #elif defined(PETSC_USE_DEBUG) 1090 1091 #define PetscStackPush_Private(stack__, file__, func__, line__, petsc_routine__, hot__) \ 1092 do { \ 1093 if (stack__.currentsize < PETSCSTACKSIZE) { \ 1094 stack__.function[stack__.currentsize] = func__; \ 1095 if (petsc_routine__) { \ 1096 stack__.file[stack__.currentsize] = file__; \ 1097 stack__.line[stack__.currentsize] = line__; \ 1098 } else { \ 1099 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 1100 stack__.line[stack__.currentsize] = 0; \ 1101 } \ 1102 stack__.petscroutine[stack__.currentsize] = petsc_routine__; \ 1103 } \ 1104 ++stack__.currentsize; \ 1105 stack__.hotdepth += (hot__ || stack__.hotdepth); \ 1106 } while (0) 1107 1108 /* uses PetscCheckAbort() because may be used in a function that does not return an error code */ 1109 #define PetscStackPop_Private(stack__, func__) \ 1110 do { \ 1111 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__); \ 1112 if (--stack__.currentsize < PETSCSTACKSIZE) { \ 1113 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", \ 1114 stack__.function[stack__.currentsize], stack__.file[stack__.currentsize], stack__.line[stack__.currentsize], func__, __FILE__, __LINE__); \ 1115 stack__.function[stack__.currentsize] = PETSC_NULLPTR; \ 1116 stack__.file[stack__.currentsize] = PETSC_NULLPTR; \ 1117 stack__.line[stack__.currentsize] = 0; \ 1118 stack__.petscroutine[stack__.currentsize] = 0; \ 1119 } \ 1120 stack__.hotdepth = PetscMax(stack__.hotdepth - 1, 0); \ 1121 } while (0) 1122 1123 /*MC 1124 PetscStackPushNoCheck - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is 1125 currently in the source code. 1126 1127 Not Collective 1128 1129 Synopsis: 1130 #include <petscsys.h> 1131 void PetscStackPushNoCheck(char *funct,int petsc_routine,PetscBool hot); 1132 1133 Input Parameters: 1134 + funct - the function name 1135 . petsc_routine - 2 user function, 1 PETSc function, 0 some other function 1136 - hot - indicates that the function may be called often so expensive error checking should be turned off inside the function 1137 1138 Level: developer 1139 1140 Notes: 1141 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 1142 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 1143 help debug the problem. 1144 1145 This version does not check the memory corruption (an expensive operation), use `PetscStackPush()` to check the memory. 1146 1147 Use `PetscStackPushExternal()` for a function call that is about to be made to a non-PETSc or user function (such as BLAS etc). 1148 1149 The default stack is a global variable called `petscstack`. 1150 1151 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1152 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPush()`, `PetscStackPop`, 1153 `PetscStackPushExternal()` 1154 M*/ 1155 #define PetscStackPushNoCheck(funct, petsc_routine, hot) \ 1156 do { \ 1157 PetscStackSAWsTakeAccess(); \ 1158 PetscStackPush_Private(petscstack, __FILE__, funct, __LINE__, petsc_routine, hot); \ 1159 PetscStackSAWsGrantAccess(); \ 1160 } while (0) 1161 1162 /*MC 1163 PetscStackUpdateLine - in a function that has a `PetscFunctionBegin` or `PetscFunctionBeginUser` updates the stack line number to the 1164 current line number. 1165 1166 Not Collective 1167 1168 Synopsis: 1169 #include <petscsys.h> 1170 void PetscStackUpdateLine 1171 1172 Level: developer 1173 1174 Notes: 1175 Using `PetscCall()` and friends automatically handles this process 1176 1177 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 1178 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1179 help debug the problem. 1180 1181 The default stack is a global variable called petscstack. 1182 1183 This is used by `PetscCall()` and is otherwise not like to be needed 1184 1185 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop`, `PetscCall()` 1186 M*/ 1187 #define PetscStackUpdateLine \ 1188 if (petscstack.currentsize > 0 && petscstack.function[petscstack.currentsize - 1] == PETSC_FUNCTION_NAME) { petscstack.line[petscstack.currentsize - 1] = __LINE__; } 1189 1190 /*MC 1191 PetscStackPushExternal - Pushes a new function name onto the PETSc default stack that tracks where the running program is 1192 currently in the source code. Does not include the filename or line number since this is called by the calling routine 1193 for non-PETSc or user functions. 1194 1195 Not Collective 1196 1197 Synopsis: 1198 #include <petscsys.h> 1199 void PetscStackPushExternal(char *funct); 1200 1201 Input Parameters: 1202 . funct - the function name 1203 1204 Level: developer 1205 1206 Notes: 1207 Using `PetscCallExternal()` and friends automatically handles this process 1208 1209 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 1210 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1211 help debug the problem. 1212 1213 The default stack is a global variable called `petscstack`. 1214 1215 This is to be used when calling an external package function such as a BLAS function. 1216 1217 This also updates the stack line number for the current stack function. 1218 1219 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1220 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1221 M*/ 1222 #define PetscStackPushExternal(funct) \ 1223 do { \ 1224 PetscStackUpdateLine; \ 1225 PetscStackPushNoCheck(funct, 0, PETSC_TRUE); \ 1226 } while (0); 1227 1228 /*MC 1229 PetscStackPopNoCheck - Pops a function name from the PETSc default stack that tracks where the running program is 1230 currently in the source code. 1231 1232 Not Collective 1233 1234 Synopsis: 1235 #include <petscsys.h> 1236 void PetscStackPopNoCheck(char *funct); 1237 1238 Input Parameter: 1239 . funct - the function name 1240 1241 Level: developer 1242 1243 Notes: 1244 Using `PetscCall()`, `PetscCallExternal()`, `PetscCallBack()` and friends negates the need to call this 1245 1246 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 1247 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1248 help debug the problem. 1249 1250 The default stack is a global variable called petscstack. 1251 1252 Developer Note: 1253 `PetscStackPopNoCheck()` takes a function argument while `PetscStackPop` does not, this difference is likely just historical. 1254 1255 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1256 M*/ 1257 #define PetscStackPopNoCheck(funct) \ 1258 do { \ 1259 PetscStackSAWsTakeAccess(); \ 1260 PetscStackPop_Private(petscstack, funct); \ 1261 PetscStackSAWsGrantAccess(); \ 1262 } while (0) 1263 1264 #define PetscStackClearTop \ 1265 do { \ 1266 PetscStackSAWsTakeAccess(); \ 1267 if (petscstack.currentsize > 0 && --petscstack.currentsize < PETSCSTACKSIZE) { \ 1268 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 1269 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 1270 petscstack.line[petscstack.currentsize] = 0; \ 1271 petscstack.petscroutine[petscstack.currentsize] = 0; \ 1272 } \ 1273 petscstack.hotdepth = PetscMax(petscstack.hotdepth - 1, 0); \ 1274 PetscStackSAWsGrantAccess(); \ 1275 } while (0) 1276 1277 /*MC 1278 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 1279 line of PETSc functions should be `PetscFunctionReturn`(0); 1280 1281 Synopsis: 1282 #include <petscsys.h> 1283 void PetscFunctionBegin; 1284 1285 Not Collective 1286 1287 Usage: 1288 .vb 1289 int something; 1290 1291 PetscFunctionBegin; 1292 .ve 1293 1294 Notes: 1295 Use `PetscFunctionBeginUser` for application codes. 1296 1297 Not available in Fortran 1298 1299 Level: developer 1300 1301 .seealso: `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()` 1302 1303 M*/ 1304 #define PetscFunctionBegin \ 1305 do { \ 1306 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_FALSE); \ 1307 PetscRegister__FUNCT__(); \ 1308 } while (0) 1309 1310 /*MC 1311 PetscFunctionBeginHot - Substitute for `PetscFunctionBegin` to be used in functions that are called in 1312 performance-critical circumstances. Use of this function allows for lighter profiling by default. 1313 1314 Synopsis: 1315 #include <petscsys.h> 1316 void PetscFunctionBeginHot; 1317 1318 Not Collective 1319 1320 Usage: 1321 .vb 1322 int something; 1323 1324 PetscFunctionBeginHot; 1325 .ve 1326 1327 Notes: 1328 Not available in Fortran 1329 1330 Level: developer 1331 1332 .seealso: `PetscFunctionBegin`, `PetscFunctionReturn()`, `PetscStackPushNoCheck()` 1333 1334 M*/ 1335 #define PetscFunctionBeginHot \ 1336 do { \ 1337 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 1, PETSC_TRUE); \ 1338 PetscRegister__FUNCT__(); \ 1339 } while (0) 1340 1341 /*MC 1342 PetscFunctionBeginUser - First executable line of user provided routines 1343 1344 Synopsis: 1345 #include <petscsys.h> 1346 void PetscFunctionBeginUser; 1347 1348 Not Collective 1349 1350 Usage: 1351 .vb 1352 int something; 1353 1354 PetscFunctionBeginUser; 1355 .ve 1356 1357 Notes: 1358 Functions that incorporate this must call `PetscFunctionReturn()` instead of return except for main(). 1359 1360 May be used before `PetscInitialize()` 1361 1362 Not available in Fortran 1363 1364 This is identical to `PetscFunctionBegin` except it labels the routine as a user 1365 routine instead of as a PETSc library routine. 1366 1367 Level: intermediate 1368 1369 .seealso: `PetscFunctionReturn()`, `PetscFunctionBegin`, `PetscFunctionBeginHot`, `PetscStackPushNoCheck()` 1370 1371 M*/ 1372 #define PetscFunctionBeginUser \ 1373 do { \ 1374 PetscStackPushNoCheck(PETSC_FUNCTION_NAME, 2, PETSC_FALSE); \ 1375 PetscRegister__FUNCT__(); \ 1376 } while (0) 1377 1378 /*MC 1379 PetscStackPush - Pushes a new function name and line number onto the PETSc default stack that tracks where the running program is 1380 currently in the source code and verifies the memory is not corrupted. 1381 1382 Not Collective 1383 1384 Synopsis: 1385 #include <petscsys.h> 1386 void PetscStackPush(char *funct) 1387 1388 Input Parameter: 1389 . funct - the function name 1390 1391 Level: developer 1392 1393 Notes: 1394 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 1395 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1396 help debug the problem. 1397 1398 The default stack is a global variable called petscstack. 1399 1400 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPopNoCheck()`, `PetscCall()`, `PetscFunctionBegin()`, 1401 `PetscFunctionReturn()`, `PetscFunctionBeginHot()`, `PetscFunctionBeginUser()`, `PetscStackPushNoCheck()`, `PetscStackPop` 1402 M*/ 1403 #define PetscStackPush(n) \ 1404 do { \ 1405 PetscStackPushNoCheck(n, 0, PETSC_FALSE); \ 1406 CHKMEMQ; \ 1407 } while (0) 1408 1409 /*MC 1410 PetscStackPop - Pops a function name from the PETSc default stack that tracks where the running program is 1411 currently in the source code and verifies the memory is not corrupted. 1412 1413 Not Collective 1414 1415 Synopsis: 1416 #include <petscsys.h> 1417 void PetscStackPop 1418 1419 Level: developer 1420 1421 Notes: 1422 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 1423 occurred, for example, when a signal is received. It is recommended to use the debugger if extensive information is needed to 1424 help debug the problem. 1425 1426 The default stack is a global variable called petscstack. 1427 1428 .seealso: `PetscAttachDebugger()`, `PetscStackCopy()`, `PetscStackView()`, `PetscStackPushNoCheck()`, `PetscStackPopNoCheck()`, `PetscStackPush()` 1429 M*/ 1430 #define PetscStackPop \ 1431 do { \ 1432 CHKMEMQ; \ 1433 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1434 } while (0) 1435 1436 /*MC 1437 PetscFunctionReturn - Last executable line of each PETSc function 1438 used for error handling. Replaces `return()` 1439 1440 Synopsis: 1441 #include <petscsys.h> 1442 void PetscFunctionReturn(0); 1443 1444 Not Collective 1445 1446 Usage: 1447 .vb 1448 .... 1449 PetscFunctionReturn(0); 1450 } 1451 .ve 1452 1453 Note: 1454 Not available in Fortran 1455 1456 Level: developer 1457 1458 .seealso: `PetscFunctionBegin()`, `PetscStackPopNoCheck()` 1459 1460 M*/ 1461 #define PetscFunctionReturn(a) \ 1462 do { \ 1463 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1464 return a; \ 1465 } while (0) 1466 1467 #define PetscFunctionReturnVoid() \ 1468 do { \ 1469 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1470 return; \ 1471 } while (0) 1472 #else /* PETSC_USE_DEBUG */ 1473 #define PetscStackPushNoCheck(funct, petsc_routine, hot) 1474 #define PetscStackUpdateLine 1475 #define PetscStackPushExternal(funct) 1476 #define PetscStackPopNoCheck 1477 #define PetscStackClearTop 1478 #define PetscFunctionBegin 1479 #define PetscFunctionBeginUser 1480 #define PetscFunctionBeginHot 1481 #define PetscFunctionReturn(a) return a 1482 #define PetscFunctionReturnVoid() return 1483 #define PetscStackPop CHKMEMQ 1484 #define PetscStackPush(f) CHKMEMQ 1485 #endif /* PETSC_USE_DEBUG */ 1486 1487 #if defined(PETSC_CLANG_STATIC_ANALYZER) 1488 #define PetscStackCallExternalVoid(name, routine) 1489 #define PetscCallExternal(func, ...) 1490 #else 1491 /*MC 1492 PetscStackCallExternalVoid - Calls an external library routine or user function after pushing the name of the routine on the stack. 1493 1494 Input Parameters: 1495 + name - string that gives the name of the function being called 1496 - routine - actual call to the routine, for example, functionname(a,b) 1497 1498 Level: developer 1499 1500 Note: 1501 Often one should use `PetscCallExternal()` instead. This routine is intended for external library routines that DO NOT return error codes 1502 1503 In debug mode this also checks the memory for corruption at the end of the function call. 1504 1505 Certain external packages, such as BLAS/LAPACK may have their own macros for managing the call, error checking, etc. 1506 1507 Developer Note: 1508 This is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1509 1510 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscCallExternal()`, `PetscCallBLAS()` 1511 @*/ 1512 #define PetscStackCallExternalVoid(name, routine) \ 1513 do { \ 1514 PetscStackPush(name); \ 1515 routine; \ 1516 PetscStackPop; \ 1517 } while (0) 1518 1519 /*MC 1520 PetscCallExternal - Calls an external library routine that returns an error code after pushing the name of the routine on the stack. 1521 1522 Input Parameters: 1523 + func- name of the routine 1524 - args - arguments to the routine 1525 1526 Level: developer 1527 1528 Notes: 1529 This is intended for external package routines that return error codes. Use `PetscStackCallExternalVoid()` for those that do not. 1530 1531 In debug mode this also checks the memory for corruption at the end of the function call. 1532 1533 Assumes the error return code of the function is an integer and that a value of 0 indicates success 1534 1535 Developer Note: 1536 This is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1537 1538 .seealso: `PetscCall()`, `PetscStackPushNoCheck()`, `PetscStackPush()`, `PetscStackCallExternalVoid()` 1539 M*/ 1540 #define PetscCallExternal(func, ...) \ 1541 do { \ 1542 PetscStackPush(PetscStringize(func)); \ 1543 PetscErrorCode __ierr = func(__VA_ARGS__); \ 1544 PetscStackPop; \ 1545 PetscCheck(!__ierr, PETSC_COMM_SELF, PETSC_ERR_LIB, "Error in %s(): error code %d", PetscStringize(func), __ierr); \ 1546 } while (0) 1547 #endif /* PETSC_CLANG_STATIC_ANALYZER */ 1548 1549 #endif 1550