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) 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) 551 #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) 552 #else 553 #define CHKERRABORT(comm,ierr) 554 #define CHKERRCONTINUE(ierr) 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 do { \ 621 PetscErrorCode _7_errorcode = (ierr); \ 622 if (PetscUnlikely(_7_errorcode)) { \ 623 char _7_errorstring[MPI_MAX_ERROR_STRING]; \ 624 PetscMPIInt _7_resultlen; \ 625 MPI_Error_string(_7_errorcode,(char*)_7_errorstring,&_7_resultlen); (void)_7_resultlen; \ 626 SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_MPI,"MPI error %d %s",(int)_7_errorcode,_7_errorstring); \ 627 } \ 628 } while (0) 629 #else 630 #define CHKERRMPI(ierr) 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 do {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while (0) 713 714 #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__) 715 #else 716 #define CHKMEMQ 717 #define CHKMEMA 718 #endif 719 /*E 720 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 721 722 Level: advanced 723 724 PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated 725 726 Developer Notes: 727 This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 728 729 .seealso: PetscError(), SETERRXX() 730 E*/ 731 typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType; 732 733 #if defined(__clang_analyzer__) 734 __attribute__((analyzer_noreturn)) 735 #endif 736 PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...) PETSC_ATTRIBUTE_FORMAT(7,8); 737 738 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 739 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **); 740 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 741 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 742 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 743 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 744 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 745 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 746 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 747 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*); 748 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 749 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*); 750 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 751 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 752 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 753 PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void); 754 PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") PETSC_STATIC_INLINE void PetscSignalSegvCheckPointer(void) {PetscSignalSegvCheckPointerOrMpi();} 755 756 /*MC 757 PetscErrorPrintf - Prints error messages. 758 759 Synopsis: 760 #include <petscsys.h> 761 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 762 763 Not Collective 764 765 Input Parameter: 766 . format - the usual printf() format string 767 768 Options Database Keys: 769 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 770 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 771 772 Notes: 773 Use 774 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 775 $ error is handled.) and 776 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 777 778 Use 779 PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file. 780 PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file. 781 782 Use 783 PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print 784 785 Level: developer 786 787 Fortran Note: 788 This routine is not supported in Fortran. 789 790 .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscPushErrorHandler(), PetscVFPrintf(), PetscHelpPrintf() 791 M*/ 792 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...) PETSC_ATTRIBUTE_FORMAT(1,2); 793 794 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 795 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 796 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 797 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 798 PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void); 799 800 /* 801 Allows the code to build a stack frame as it runs 802 */ 803 804 #if defined(PETSC_USE_DEBUG) 805 #define PETSCSTACKSIZE 64 806 typedef struct { 807 const char *function[PETSCSTACKSIZE]; 808 const char *file[PETSCSTACKSIZE]; 809 int line[PETSCSTACKSIZE]; 810 int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */ 811 int currentsize; 812 int hotdepth; 813 PetscBool check; /* runtime option to check for correct Push/Pop semantics at runtime */ 814 } PetscStack; 815 PETSC_EXTERN PetscStack petscstack; 816 #else 817 typedef struct { 818 char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp; 819 } PetscStack; 820 #endif 821 822 #if defined(PETSC_SERIALIZE_FUNCTIONS) 823 #include <petsc/private/petscfptimpl.h> 824 /* 825 Registers the current function into the global function pointer to function name table 826 827 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 828 */ 829 #define PetscRegister__FUNCT__() do { \ 830 static PetscBool __chked = PETSC_FALSE; \ 831 if (!__chked) {\ 832 void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\ 833 __chked = PETSC_TRUE;\ 834 }} while (0) 835 #else 836 #define PetscRegister__FUNCT__() 837 #endif 838 839 #if !defined(PETSC_CLANG_STATIC_ANALYZER) 840 #if defined(PETSC_USE_DEBUG) 841 842 /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error 843 * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at 844 * least more useful than "unknown" because it can distinguish multiple calls from the same function. 845 */ 846 #define PetscStackPushNoCheck(funct,petsc_routine,hot) do { \ 847 PetscStackSAWsTakeAccess(); \ 848 if (petscstack.currentsize < PETSCSTACKSIZE) { \ 849 petscstack.function[petscstack.currentsize] = funct; \ 850 petscstack.file[petscstack.currentsize] = __FILE__; \ 851 petscstack.line[petscstack.currentsize] = __LINE__; \ 852 petscstack.petscroutine[petscstack.currentsize] = petsc_routine; \ 853 } \ 854 ++petscstack.currentsize; \ 855 petscstack.hotdepth += (hot || petscstack.hotdepth); \ 856 PetscStackSAWsGrantAccess(); \ 857 } while (0) 858 859 #define PetscStackPopNoCheck(funct) do { \ 860 PetscStackSAWsTakeAccess(); \ 861 if (PetscUnlikely(petscstack.currentsize <= 0)) { \ 862 if (PetscUnlikely(petscstack.check)) { \ 863 printf("Invalid stack size %d, pop %s\n", \ 864 petscstack.currentsize,funct); \ 865 } \ 866 } else { \ 867 if (--petscstack.currentsize < PETSCSTACKSIZE) { \ 868 if (PetscUnlikely( \ 869 petscstack.check && \ 870 petscstack.petscroutine[petscstack.currentsize] && \ 871 (petscstack.function[petscstack.currentsize] != \ 872 (const char*)funct))) { \ 873 /* We need this string comparison because "unknown" can be defined in different static strings: */ \ 874 PetscBool _cmpflg; \ 875 const char *_funct = petscstack.function[petscstack.currentsize]; \ 876 PetscStrcmp(_funct,funct,&_cmpflg); \ 877 if (!_cmpflg) \ 878 printf("Invalid stack: push from %s, pop from %s\n", _funct,funct); \ 879 } \ 880 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 881 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 882 petscstack.line[petscstack.currentsize] = 0; \ 883 petscstack.petscroutine[petscstack.currentsize] = 0; \ 884 } \ 885 petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \ 886 } \ 887 PetscStackSAWsGrantAccess(); \ 888 } while (0) 889 890 #define PetscStackClearTop do { \ 891 PetscStackSAWsTakeAccess(); \ 892 if (petscstack.currentsize > 0 && \ 893 --petscstack.currentsize < PETSCSTACKSIZE) { \ 894 petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \ 895 petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \ 896 petscstack.line[petscstack.currentsize] = 0; \ 897 petscstack.petscroutine[petscstack.currentsize] = 0; \ 898 } \ 899 petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \ 900 PetscStackSAWsGrantAccess(); \ 901 } while (0) 902 903 /*MC 904 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 905 line of PETSc functions should be PetscFunctionReturn(0); 906 907 Synopsis: 908 #include <petscsys.h> 909 void PetscFunctionBegin; 910 911 Not Collective 912 913 Usage: 914 .vb 915 int something; 916 917 PetscFunctionBegin; 918 .ve 919 920 Notes: 921 Use PetscFunctionBeginUser for application codes. 922 923 Not available in Fortran 924 925 Level: developer 926 927 .seealso: PetscFunctionReturn(), PetscFunctionBeginHot(), PetscFunctionBeginUser() 928 929 M*/ 930 #define PetscFunctionBegin do { \ 931 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_FALSE); \ 932 PetscRegister__FUNCT__(); \ 933 } while (0) 934 935 /*MC 936 PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in 937 performance-critical circumstances. Use of this function allows for lighter profiling by default. 938 939 Synopsis: 940 #include <petscsys.h> 941 void PetscFunctionBeginHot; 942 943 Not Collective 944 945 Usage: 946 .vb 947 int something; 948 949 PetscFunctionBeginHot; 950 .ve 951 952 Notes: 953 Not available in Fortran 954 955 Level: developer 956 957 .seealso: PetscFunctionBegin, PetscFunctionReturn() 958 959 M*/ 960 #define PetscFunctionBeginHot do { \ 961 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_TRUE); \ 962 PetscRegister__FUNCT__(); \ 963 } while (0) 964 965 /*MC 966 PetscFunctionBeginUser - First executable line of user provided PETSc routine 967 968 Synopsis: 969 #include <petscsys.h> 970 void PetscFunctionBeginUser; 971 972 Not Collective 973 974 Usage: 975 .vb 976 int something; 977 978 PetscFunctionBeginUser; 979 .ve 980 981 Notes: 982 Final line of PETSc functions should be PetscFunctionReturn(0) except for main(). 983 984 Not available in Fortran 985 986 This is identical to PetscFunctionBegin except it labels the routine as a user 987 routine instead of as a PETSc library routine. 988 989 Level: intermediate 990 991 .seealso: PetscFunctionReturn(), PetscFunctionBegin, PetscFunctionBeginHot 992 993 M*/ 994 #define PetscFunctionBeginUser do { \ 995 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,2,PETSC_FALSE); \ 996 PetscRegister__FUNCT__(); \ 997 } while (0) 998 999 #define PetscStackPush(n) do { \ 1000 PetscStackPushNoCheck(n,0,PETSC_FALSE); \ 1001 CHKMEMQ; \ 1002 } while (0) 1003 1004 #define PetscStackPop do { \ 1005 CHKMEMQ; \ 1006 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1007 } while (0) 1008 1009 /*MC 1010 PetscFunctionReturn - Last executable line of each PETSc function 1011 used for error handling. Replaces return() 1012 1013 Synopsis: 1014 #include <petscsys.h> 1015 void PetscFunctionReturn(0); 1016 1017 Not Collective 1018 1019 Usage: 1020 .vb 1021 .... 1022 PetscFunctionReturn(0); 1023 } 1024 .ve 1025 1026 Notes: 1027 Not available in Fortran 1028 1029 Level: developer 1030 1031 .seealso: PetscFunctionBegin() 1032 1033 M*/ 1034 #define PetscFunctionReturn(a) do { \ 1035 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1036 return a; \ 1037 } while (0) 1038 1039 #define PetscFunctionReturnVoid() do { \ 1040 PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \ 1041 return; \ 1042 } while (0) 1043 #else /* PETSC_USE_DEBUG */ 1044 1045 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 1046 #define PetscStackPopNoCheck 1047 #define PetscStackClearTop 1048 #define PetscFunctionBegin 1049 #define PetscFunctionBeginUser 1050 #define PetscFunctionBeginHot 1051 #define PetscFunctionReturn(a) return a 1052 #define PetscFunctionReturnVoid() return 1053 #define PetscStackPop CHKMEMQ 1054 #define PetscStackPush(f) CHKMEMQ 1055 1056 #endif /* PETSC_USE_DEBUG */ 1057 1058 /* 1059 PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack. 1060 1061 Input Parameters: 1062 + name - string that gives the name of the function being called 1063 - routine - actual call to the routine, including ierr = and CHKERRQ(ierr); 1064 1065 Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes 1066 1067 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. 1068 1069 */ 1070 #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while (0) 1071 1072 /* 1073 PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack. 1074 1075 Input Parameters: 1076 + func- name of the routine 1077 - args - arguments to the routine surrounded by () 1078 1079 Notes: 1080 This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not. 1081 1082 Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 1083 1084 */ 1085 #define PetscStackCallStandard(func,args) do { \ 1086 PetscErrorCode __ierr; \ 1087 PetscStackPush(#func); \ 1088 __ierr = func args; \ 1089 PetscStackPop; \ 1090 if (__ierr) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",#func,(int)__ierr); \ 1091 } while (0) 1092 1093 #else /* !PETSC_CLANG_STATIC_ANALYZER */ 1094 #define PetscStackPushNoCheck(funct,petsc_routine,hot) 1095 #define PetscStackPopNoCheck 1096 #define PetscStackClearTop 1097 #define PetscFunctionBegin 1098 #define PetscFunctionBeginUser 1099 #define PetscFunctionBeginHot 1100 #define PetscFunctionReturn(a) return a 1101 #define PetscFunctionReturnVoid() return 1102 #define PetscStackPop 1103 #define PetscStackPush(f) 1104 #define PetscStackCall(name,routine) 1105 #define PetscStackCallStandard(name,routine) 1106 #endif /* !PETSC_CLANG_STATIC_ANALYZER */ 1107 1108 #endif 1109