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 include/petsc/finclude/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 32 #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */ 33 #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */ 34 #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */ 35 #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */ 36 #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */ 37 #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */ 38 #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */ 39 #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */ 40 #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */ 41 #define PETSC_ERR_ARG_TYPENOTSET 89 /* the type of the object has not yet been set */ 42 #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */ 43 #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */ 44 #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */ 45 46 #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */ 47 #define PETSC_ERR_FILE_READ 66 /* unable to read from file */ 48 #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */ 49 #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */ 50 51 #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */ 52 #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */ 53 54 #define PETSC_ERR_INT_OVERFLOW 84 55 56 #define PETSC_ERR_FLOP_COUNT 90 57 #define PETSC_ERR_NOT_CONVERGED 91 /* solver did not converge */ 58 #define PETSC_ERR_MISSING_FACTOR 92 /* MatGetFactor() failed */ 59 #define PETSC_ERR_OPT_OVERWRITE 93 /* attempted to over wrote options which should not be changed */ 60 61 #define PETSC_ERR_MAX_VALUE 94 /* this is always the one more than the largest error code */ 62 63 #define PetscStringizeArg(a) #a 64 #define PetscStringize(a) PetscStringizeArg(a) 65 66 #if defined(PETSC_USE_ERRORCHECKING) 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 on MPI_Comm 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 In Fortran MPI_Abort() is always called 90 91 Experienced users can set the error handler with PetscPushErrorHandler(). 92 93 Concepts: error^setting condition 94 95 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3() 96 M*/ 97 #define SETERRQ(comm,ierr,s) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s) 98 99 /*MC 100 SETERRQ1 - Macro that is called when an error has been detected, 101 102 Synopsis: 103 #include <petscsys.h> 104 PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg) 105 106 Collective on MPI_Comm 107 108 Input Parameters: 109 + comm - A communicator, so that the error can be collective 110 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 111 . message - error message in the printf format 112 - arg - argument (for example an integer, string or double) 113 114 Level: beginner 115 116 Notes: 117 Once the error handler is called the calling function is then returned from with the given error code. 118 119 Experienced users can set the error handler with PetscPushErrorHandler(). 120 121 Concepts: error^setting condition 122 123 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3() 124 M*/ 125 #define SETERRQ1(comm,ierr,s,a1) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1) 126 127 /*MC 128 SETERRQ2 - Macro that is called when an error has been detected, 129 130 Synopsis: 131 #include <petscsys.h> 132 PetscErrorCode SETERRQ2(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2) 133 134 Collective on MPI_Comm 135 136 Input Parameters: 137 + comm - A communicator, so that the error can be collective 138 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 139 . message - error message in the printf format 140 . arg1 - argument (for example an integer, string or double) 141 - arg2 - argument (for example an integer, string or double) 142 143 Level: beginner 144 145 Notes: 146 Once the error handler is called the calling function is then returned from with the given error code. 147 148 Experienced users can set the error handler with PetscPushErrorHandler(). 149 150 Concepts: error^setting condition 151 152 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3() 153 M*/ 154 #define SETERRQ2(comm,ierr,s,a1,a2) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2) 155 156 /*MC 157 SETERRQ3 - Macro that is called when an error has been detected, 158 159 Synopsis: 160 #include <petscsys.h> 161 PetscErrorCode SETERRQ3(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 162 163 Collective on MPI_Comm 164 165 Input Parameters: 166 + comm - A communicator, so that the error can be collective 167 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 168 . message - error message in the printf format 169 . arg1 - argument (for example an integer, string or double) 170 . arg2 - argument (for example an integer, string or double) 171 - arg3 - 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 There are also versions for 4, 5, 6 and 7 arguments. 179 180 Experienced users can set the error handler with PetscPushErrorHandler(). 181 182 Concepts: error^setting condition 183 184 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 185 M*/ 186 #define SETERRQ3(comm,ierr,s,a1,a2,a3) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3) 187 188 /*MC 189 SETERRQ4 - Macro that is called when an error has been detected, 190 191 Synopsis: 192 #include <petscsys.h> 193 PetscErrorCode SETERRQ4(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 194 195 Collective on MPI_Comm 196 197 Input Parameters: 198 + comm - A communicator, so that the error can be collective 199 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 200 . message - error message in the printf format 201 . arg1 - argument (for example an integer, string or double) 202 . arg2 - argument (for example an integer, string or double) 203 . arg3 - argument (for example an integer, string or double) 204 - arg4 - argument (for example an integer, string or double) 205 206 Level: beginner 207 208 Notes: 209 Once the error handler is called the calling function is then returned from with the given error code. 210 211 There are also versions for 4, 5, 6 and 7 arguments. 212 213 Experienced users can set the error handler with PetscPushErrorHandler(). 214 215 Concepts: error^setting condition 216 217 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 218 M*/ 219 #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) 220 221 /*MC 222 SETERRQ5 - Macro that is called when an error has been detected, 223 224 Synopsis: 225 #include <petscsys.h> 226 PetscErrorCode SETERRQ5(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 227 228 Collective on MPI_COmm 229 230 Input Parameters: 231 + comm - A communicator, so that the error can be collective 232 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 233 . message - error message in the printf format 234 . arg1 - argument (for example an integer, string or double) 235 . arg2 - argument (for example an integer, string or double) 236 . arg3 - argument (for example an integer, string or double) 237 . arg4 - argument (for example an integer, string or double) 238 - arg5 - argument (for example an integer, string or double) 239 240 Level: beginner 241 242 Notes: 243 Once the error handler is called the calling function is then returned from with the given error code. 244 245 There are also versions for 4, 5, 6 and 7 arguments. 246 247 Experienced users can set the error handler with PetscPushErrorHandler(). 248 249 Concepts: error^setting condition 250 251 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 252 M*/ 253 #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) 254 255 /*MC 256 SETERRQ6 - Macro that is called when an error has been detected, 257 258 Synopsis: 259 #include <petscsys.h> 260 PetscErrorCode SETERRQ6(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 261 262 Collective on MPI_Comm 263 264 Input Parameters: 265 + comm - A communicator, so that the error can be collective 266 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 267 . message - error message in the printf format 268 . arg1 - argument (for example an integer, string or double) 269 . arg2 - argument (for example an integer, string or double) 270 . arg3 - argument (for example an integer, string or double) 271 . arg4 - argument (for example an integer, string or double) 272 . arg5 - argument (for example an integer, string or double) 273 - arg6 - argument (for example an integer, string or double) 274 275 Level: beginner 276 277 Notes: 278 Once the error handler is called the calling function is then returned from with the given error code. 279 280 There are also versions for 4, 5, 6 and 7 arguments. 281 282 Experienced users can set the error handler with PetscPushErrorHandler(). 283 284 Concepts: error^setting condition 285 286 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 287 M*/ 288 #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) 289 290 /*MC 291 SETERRQ7 - Macro that is called when an error has been detected, 292 293 Synopsis: 294 #include <petscsys.h> 295 PetscErrorCode SETERRQ7(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 296 297 Collective on MPI_Comm 298 299 Input Parameters: 300 + comm - A communicator, so that the error can be collective 301 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 302 . message - error message in the printf format 303 . arg1 - argument (for example an integer, string or double) 304 . arg2 - argument (for example an integer, string or double) 305 . arg3 - argument (for example an integer, string or double) 306 . arg4 - argument (for example an integer, string or double) 307 . arg5 - argument (for example an integer, string or double) 308 . arg6 - argument (for example an integer, string or double) 309 - arg7 - argument (for example an integer, string or double) 310 311 Level: beginner 312 313 Notes: 314 Once the error handler is called the calling function is then returned from with the given error code. 315 316 There are also versions for 4, 5, 6 and 7 arguments. 317 318 Experienced users can set the error handler with PetscPushErrorHandler(). 319 320 Concepts: error^setting condition 321 322 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 323 M*/ 324 #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) 325 326 /*MC 327 SETERRQ8 - Macro that is called when an error has been detected, 328 329 Synopsis: 330 #include <petscsys.h> 331 PetscErrorCode SETERRQ8(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3) 332 333 Collective on MPI_Comm 334 335 Input Parameters: 336 + comm - A communicator, so that the error can be collective 337 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 338 . message - error message in the printf format 339 . arg1 - argument (for example an integer, string or double) 340 . arg2 - argument (for example an integer, string or double) 341 . arg3 - argument (for example an integer, string or double) 342 . arg4 - argument (for example an integer, string or double) 343 . arg5 - argument (for example an integer, string or double) 344 . arg6 - argument (for example an integer, string or double) 345 . arg7 - argument (for example an integer, string or double) 346 - arg8 - argument (for example an integer, string or double) 347 348 Level: beginner 349 350 Notes: 351 Once the error handler is called the calling function is then returned from with the given error code. 352 353 There are also versions for 4, 5, 6 and 7 arguments. 354 355 Experienced users can set the error handler with PetscPushErrorHandler(). 356 357 Concepts: error^setting condition 358 359 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 360 M*/ 361 #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) 362 363 /*MC 364 SETERRABORT - Macro that can be called when an error has been detected, 365 366 Synopsis: 367 #include <petscsys.h> 368 PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message) 369 370 Collective on MPI_Comm 371 372 Input Parameters: 373 + comm - A communicator, so that the error can be collective 374 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 375 - message - error message in the printf format 376 377 Level: beginner 378 379 Notes: 380 This function just calls MPI_Abort(). 381 382 Concepts: error^setting condition 383 384 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2() 385 M*/ 386 #define SETERRABORT(comm,ierr,s) do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,ierr);} while (0) 387 388 /*MC 389 CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns 390 391 Synopsis: 392 #include <petscsys.h> 393 PetscErrorCode CHKERRQ(PetscErrorCode ierr) 394 395 Not Collective 396 397 Input Parameters: 398 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 399 400 Level: beginner 401 402 Notes: 403 Once the error handler is called the calling function is then returned from with the given error code. 404 405 Experienced users can set the error handler with PetscPushErrorHandler(). 406 407 CHKERRQ(ierr) is fundamentally a macro replacement for 408 if (ierr) return(PetscError(...,ierr,...)); 409 410 Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is 411 highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular, 412 it cannot be used in functions which return(void) or any other datatype. In these types of functions, 413 you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or 414 if (ierr) {PetscError(....); return(YourReturnType);} 415 where you may pass back a NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have 416 MPI_Abort() returned immediately. 417 418 In Fortran MPI_Abort() is always called 419 420 Concepts: error^setting condition 421 422 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2() 423 M*/ 424 #define CHKERRQ(ierr) do {if (PetscUnlikely(ierr)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");} while (0) 425 426 #define CHKERRV(ierr) do {if (PetscUnlikely(ierr)) {ierr = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");return;}} while(0) 427 #define CHKERRABORT(comm,ierr) do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,ierr);}} while (0) 428 #define CHKERRCONTINUE(ierr) do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_REPEAT," ");}} while (0) 429 430 #ifdef PETSC_CLANGUAGE_CXX 431 432 /*MC 433 CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception 434 435 Synopsis: 436 #include <petscsys.h> 437 void CHKERRXX(PetscErrorCode ierr) 438 439 Not Collective 440 441 Input Parameters: 442 . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h 443 444 Level: beginner 445 446 Notes: 447 Once the error handler throws a ??? exception. 448 449 You can use CHKERRV() which returns without an error code (bad idea since the error is ignored) 450 or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately. 451 452 Concepts: error^setting condition 453 454 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ 455 M*/ 456 #define CHKERRXX(ierr) do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_IN_CXX,0);}} while(0) 457 458 #endif 459 460 #define CHKERRCUDA(err) do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"CUDA error %d",err);} while(0) 461 #define CHKERRCUBLAS(err) do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"CUBLAS error %d",err);} while(0) 462 463 /*MC 464 CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected 465 466 Synopsis: 467 #include <petscsys.h> 468 CHKMEMQ; 469 470 Not Collective 471 472 Level: beginner 473 474 Notes: 475 We highly recommend using valgrind http://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind for finding memory problems. This is useful 476 on systems that do not have valgrind, but much much less useful. 477 478 Must run with the option -malloc_debug to enable this option 479 480 Once the error handler is called the calling function is then returned from with the given error code. 481 482 By defaults prints location where memory that is corrupted was allocated. 483 484 Use CHKMEMA for functions that return void 485 486 Concepts: memory corruption 487 488 .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 489 PetscMallocValidate() 490 M*/ 491 #define CHKMEMQ do {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while(0) 492 493 #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__) 494 495 #else /* PETSC_USE_ERRORCHECKING */ 496 497 /* 498 These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0 499 */ 500 501 #define SETERRQ(c,ierr,s) 502 #define SETERRQ1(c,ierr,s,a1) 503 #define SETERRQ2(c,ierr,s,a1,a2) 504 #define SETERRQ3(c,ierr,s,a1,a2,a3) 505 #define SETERRQ4(c,ierr,s,a1,a2,a3,a4) 506 #define SETERRQ5(c,ierr,s,a1,a2,a3,a4,a5) 507 #define SETERRQ6(c,ierr,s,a1,a2,a3,a4,a5,a6) 508 #define SETERRQ7(c,ierr,s,a1,a2,a3,a4,a5,a6,a7) 509 #define SETERRQ8(c,ierr,s,a1,a2,a3,a4,a5,a6,a7,a8) 510 #define SETERRABORT(comm,ierr,s) 511 512 #define CHKERRQ(ierr) ; 513 #define CHKERRV(ierr) ; 514 #define CHKERRABORT(comm,n) ; 515 #define CHKERRCONTINUE(ierr) ; 516 #define CHKMEMQ ; 517 #define CHKERRCUDA(err) ; 518 #define CHKERRCUBLAS(err) ; 519 520 #ifdef PETSC_CLANGUAGE_CXX 521 #define CHKERRXX(ierr) ; 522 #endif 523 524 #endif /* PETSC_USE_ERRORCHECKING */ 525 526 /*E 527 PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers 528 529 Level: advanced 530 531 PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated 532 533 Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler() 534 535 .seealso: PetscError(), SETERRXX() 536 E*/ 537 typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType; 538 539 #if defined(__clang_analyzer__) 540 __attribute__((analyzer_noreturn)) 541 #endif 542 PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...); 543 544 PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void); 545 PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **); 546 PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 547 PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 548 PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 549 PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 550 PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 551 PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 552 PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*); 553 PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*); 554 PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void); 555 PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*); 556 PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*); 557 PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void); 558 PETSC_EXTERN PetscErrorCode PetscCheckPointerSetIntensity(PetscInt); 559 560 /*MC 561 PetscErrorPrintf - Prints error messages. 562 563 Synopsis: 564 #include <petscsys.h> 565 PetscErrorCode (*PetscErrorPrintf)(const char format[],...); 566 567 Not Collective 568 569 Input Parameters: 570 . format - the usual printf() format string 571 572 Options Database Keys: 573 + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr 574 - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.) 575 576 Notes: Use 577 $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the 578 $ error is handled.) and 579 $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function 580 581 Use 582 PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file. 583 PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file. 584 585 Use 586 PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print 587 588 Level: developer 589 590 Fortran Note: 591 This routine is not supported in Fortran. 592 593 Concepts: error messages^printing 594 Concepts: printing^error messages 595 596 .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscErrorHandlerPush(), PetscVFPrintf(), PetscHelpPrintf() 597 M*/ 598 PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...); 599 600 typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap; 601 PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap); 602 PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap); 603 PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void); 604 605 /* 606 Allows the code to build a stack frame as it runs 607 */ 608 609 #define PETSCSTACKSIZE 64 610 611 typedef struct { 612 const char *function[PETSCSTACKSIZE]; 613 const char *file[PETSCSTACKSIZE]; 614 int line[PETSCSTACKSIZE]; 615 PetscBool petscroutine[PETSCSTACKSIZE]; 616 int currentsize; 617 int hotdepth; 618 } PetscStack; 619 620 PETSC_EXTERN PetscStack *petscstack; 621 622 PetscErrorCode PetscStackCopy(PetscStack*,PetscStack*); 623 PetscErrorCode PetscStackPrint(PetscStack *,FILE*); 624 #if defined(PETSC_SERIALIZE_FUNCTIONS) 625 #include <petsc/private/petscfptimpl.h> 626 /* 627 Registers the current function into the global function pointer to function name table 628 629 Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc 630 */ 631 #define PetscRegister__FUNCT__() do { \ 632 static PetscBool __chked = PETSC_FALSE; \ 633 if (!__chked) {\ 634 void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\ 635 __chked = PETSC_TRUE;\ 636 }} while (0) 637 #else 638 #define PetscRegister__FUNCT__() 639 #endif 640 641 #if defined(PETSC_USE_DEBUG) 642 PETSC_STATIC_INLINE PetscBool PetscStackActive(void) 643 { 644 return(petscstack ? PETSC_TRUE : PETSC_FALSE); 645 } 646 647 /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error 648 * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at 649 * least more useful than "unknown" because it can distinguish multiple calls from the same function. 650 */ 651 652 #define PetscStackPushNoCheck(funct,petsc_routine,hot) \ 653 do { \ 654 PetscStackSAWsTakeAccess(); \ 655 if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \ 656 petscstack->function[petscstack->currentsize] = funct; \ 657 petscstack->file[petscstack->currentsize] = __FILE__; \ 658 petscstack->line[petscstack->currentsize] = __LINE__; \ 659 petscstack->petscroutine[petscstack->currentsize] = petsc_routine; \ 660 petscstack->currentsize++; \ 661 } \ 662 if (petscstack) { \ 663 petscstack->hotdepth += (hot || petscstack->hotdepth); \ 664 } \ 665 PetscStackSAWsGrantAccess(); \ 666 } while (0) 667 668 #define PetscStackPopNoCheck \ 669 do { \ 670 PetscStackSAWsTakeAccess(); \ 671 if (petscstack && petscstack->currentsize > 0) { \ 672 petscstack->currentsize--; \ 673 petscstack->function[petscstack->currentsize] = 0; \ 674 petscstack->file[petscstack->currentsize] = 0; \ 675 petscstack->line[petscstack->currentsize] = 0; \ 676 petscstack->petscroutine[petscstack->currentsize] = PETSC_FALSE;\ 677 } \ 678 if (petscstack) { \ 679 petscstack->hotdepth = PetscMax(petscstack->hotdepth-1,0); \ 680 } \ 681 PetscStackSAWsGrantAccess(); \ 682 } while (0) 683 684 /*MC 685 PetscFunctionBegin - First executable line of each PETSc function, used for error handling. Final 686 line of PETSc functions should be PetscFunctionReturn(0); 687 688 Synopsis: 689 #include <petscsys.h> 690 void PetscFunctionBegin; 691 692 Not Collective 693 694 Usage: 695 .vb 696 int something; 697 698 PetscFunctionBegin; 699 .ve 700 701 Notes: 702 Use PetscFunctionBeginUser for application codes. 703 704 Not available in Fortran 705 706 Level: developer 707 708 .seealso: PetscFunctionReturn(), PetscFunctionBeginHot(), PetscFunctionBeginUser() 709 710 .keywords: traceback, error handling 711 M*/ 712 #define PetscFunctionBegin do { \ 713 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_FALSE); \ 714 PetscRegister__FUNCT__(); \ 715 } while (0) 716 717 /*MC 718 PetscFunctionBeginHot - Substitute for PetscFunctionBegin to be used in functions that are called in 719 performance-critical circumstances. Use of this function allows for lighter profiling by default. 720 721 Synopsis: 722 #include <petscsys.h> 723 void PetscFunctionBeginHot; 724 725 Not Collective 726 727 Usage: 728 .vb 729 int something; 730 731 PetscFunctionBeginHot; 732 .ve 733 734 Notes: 735 Not available in Fortran 736 737 Level: developer 738 739 .seealso: PetscFunctionBegin, PetscFunctionReturn() 740 741 .keywords: traceback, error handling 742 M*/ 743 #define PetscFunctionBeginHot do { \ 744 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_TRUE); \ 745 PetscRegister__FUNCT__(); \ 746 } while (0) 747 748 /*MC 749 PetscFunctionBeginUser - First executable line of user provided PETSc routine 750 751 Synopsis: 752 #include <petscsys.h> 753 void PetscFunctionBeginUser; 754 755 Not Collective 756 757 Usage: 758 .vb 759 int something; 760 761 PetscFunctionBeginUser; 762 .ve 763 764 Notes: 765 Final line of PETSc functions should be PetscFunctionReturn(0) except for main(). 766 767 Not available in Fortran 768 769 This is identical to PetscFunctionBegin except it labels the routine as a user 770 routine instead of as a PETSc library routine. 771 772 Level: intermediate 773 774 .seealso: PetscFunctionReturn(), PetscFunctionBegin, PetscFunctionBeginHot 775 776 .keywords: traceback, error handling 777 M*/ 778 #define PetscFunctionBeginUser \ 779 do { \ 780 PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_FALSE,PETSC_FALSE); \ 781 PetscRegister__FUNCT__(); \ 782 } while (0) 783 784 785 #define PetscStackPush(n) \ 786 do { \ 787 PetscStackPushNoCheck(n,PETSC_FALSE,PETSC_FALSE); \ 788 CHKMEMQ; \ 789 } while (0) 790 791 #define PetscStackPop \ 792 do { \ 793 CHKMEMQ; \ 794 PetscStackPopNoCheck; \ 795 } while (0) 796 797 /*MC 798 PetscFunctionReturn - Last executable line of each PETSc function 799 used for error handling. Replaces return() 800 801 Synopsis: 802 #include <petscsys.h> 803 void PetscFunctionReturn(0); 804 805 Not Collective 806 807 Usage: 808 .vb 809 .... 810 PetscFunctionReturn(0); 811 } 812 .ve 813 814 Notes: 815 Not available in Fortran 816 817 Level: developer 818 819 .seealso: PetscFunctionBegin() 820 821 .keywords: traceback, error handling 822 M*/ 823 #define PetscFunctionReturn(a) \ 824 do { \ 825 PetscStackPopNoCheck; \ 826 return(a);} while (0) 827 828 #define PetscFunctionReturnVoid() \ 829 do { \ 830 PetscStackPopNoCheck; \ 831 return;} while (0) 832 833 #else 834 835 PETSC_STATIC_INLINE PetscBool PetscStackActive(void) {return PETSC_FALSE;} 836 #define PetscStackPushNoCheck(funct,petsc_routine,hot) do {} while (0) 837 #define PetscStackPopNoCheck do {} while (0) 838 #define PetscFunctionBegin 839 #define PetscFunctionBeginUser 840 #define PetscFunctionBeginHot 841 #define PetscFunctionReturn(a) return(a) 842 #define PetscFunctionReturnVoid() return 843 #define PetscStackPop CHKMEMQ 844 #define PetscStackPush(f) CHKMEMQ 845 846 #endif 847 848 /* 849 PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack. 850 851 Input Parameters: 852 + name - string that gives the name of the function being called 853 - routine - actual call to the routine, including ierr = and CHKERRQ(ierr); 854 855 Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes 856 857 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. 858 859 860 861 */ 862 #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while(0) 863 864 /* 865 PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack. 866 867 Input Parameters: 868 + func- name of the routine 869 - args - arguments to the routine surrounded by () 870 871 Notes: This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not. 872 873 Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc. 874 875 */ 876 #define PetscStackCallStandard(func,args) do { \ 877 PetscStackPush(#func);ierr = func args;PetscStackPop; if (ierr) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",#func,(int)ierr); \ 878 } while (0) 879 880 PETSC_EXTERN PetscErrorCode PetscStackCreate(void); 881 PETSC_EXTERN PetscErrorCode PetscStackView(FILE*); 882 PETSC_EXTERN PetscErrorCode PetscStackDestroy(void); 883 884 #endif 885