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