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