Actual source code: petscerror.h
1: /*
2: Contains all error handling interfaces for PETSc.
3: */
4: #if !defined(PETSCERROR_H)
5: #define PETSCERROR_H
7: #include <petscmacros.h>
8: #include <petscsystypes.h>
10: /*
11: These are the generic error codes. These error codes are used
12: many different places in the PETSc source code. The string versions are
13: at src/sys/error/err.c any changes here must also be made there
14: These are also define in src/sys/f90-mod/petscerror.h any CHANGES here
15: must be also made there.
17: */
18: #define PETSC_ERR_MIN_VALUE 54 /* should always be one less then the smallest value */
20: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
21: #define PETSC_ERR_SUP 56 /* no support for requested operation */
22: #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */
23: #define PETSC_ERR_ORDER 58 /* operation done in wrong order */
24: #define PETSC_ERR_SIG 59 /* signal received */
25: #define PETSC_ERR_FP 72 /* floating point exception */
26: #define PETSC_ERR_COR 74 /* corrupted PETSc object */
27: #define PETSC_ERR_LIB 76 /* error in library called by PETSc */
28: #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */
29: #define PETSC_ERR_MEMC 78 /* memory corruption */
30: #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */
31: #define PETSC_ERR_USER 83 /* user has not provided needed function */
32: #define PETSC_ERR_SYS 88 /* error in system call */
33: #define PETSC_ERR_POINTER 70 /* pointer does not point to valid address */
34: #define PETSC_ERR_MPI_LIB_INCOMP 87 /* MPI library at runtime is not compatible with MPI user compiled with */
36: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
37: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
38: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
39: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
40: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
41: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
42: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
43: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
44: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
45: #define PETSC_ERR_ARG_TYPENOTSET 89 /* the type of the object has not yet been set */
46: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
47: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
48: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */
50: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
51: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
52: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
53: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
55: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
56: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
58: #define PETSC_ERR_INT_OVERFLOW 84
60: #define PETSC_ERR_FLOP_COUNT 90
61: #define PETSC_ERR_NOT_CONVERGED 91 /* solver did not converge */
62: #define PETSC_ERR_MISSING_FACTOR 92 /* MatGetFactor() failed */
63: #define PETSC_ERR_OPT_OVERWRITE 93 /* attempted to over write options which should not be changed */
64: #define PETSC_ERR_WRONG_MPI_SIZE 94 /* example/application run with number of MPI ranks it does not support */
65: #define PETSC_ERR_USER_INPUT 95 /* missing or incorrect user input */
66: #define PETSC_ERR_GPU_RESOURCE 96 /* unable to load a GPU resource, for example cuBLAS */
67: #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 */
68: #define PETSC_ERR_MPI 98 /* general MPI error */
69: #define PETSC_ERR_MAX_VALUE 99 /* this is always the one more than the largest error code */
71: #define SETERRQ1(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
72: #define SETERRQ2(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
73: #define SETERRQ3(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
74: #define SETERRQ4(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
75: #define SETERRQ5(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
76: #define SETERRQ6(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
77: #define SETERRQ7(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
78: #define SETERRQ8(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
79: #define SETERRQ9(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use SETERRQ() (since version 3.17)\"") SETERRQ(__VA_ARGS__)
81: /*MC
82: SETERRQ - Macro to be called when an error has been detected,
84: Synopsis:
85: #include <petscsys.h>
86: PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message,...)
88: Collective
90: Input Parameters:
91: + comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
92: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
93: - message - error message
95: Level: beginner
97: Notes:
98: Once the error handler is called the calling function is then returned from with the given error code.
100: Experienced users can set the error handler with PetscPushErrorHandler().
102: Fortran Notes:
103: SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the
104: Fortran main program.
107: PetscError(), PetscCall(), CHKMEMQ, CHKERRA(), PetscCallMPI()
108: M*/
109: #define SETERRQ(comm,ierr,...) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__)
111: /*
112: Returned from PETSc functions that are called from MPI, such as related to attributes
113: Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as
114: an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call.
115: */
116: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS;
117: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE;
119: /*MC
120: SETERRMPI - Macro to be called when an error has been detected within an MPI callback function
122: Synopsis:
123: #include <petscsys.h>
124: PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message,...)
126: Collective
128: Input Parameters:
129: + comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
130: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
131: - message - error message
133: Level: developer
135: Notes:
136: 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
137: which is registered with MPI_Add_error_code() when PETSc is initialized.
139: .seealso: SETERRQ(), PetscCall(), PetscCallMPI(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKMEMQ
140: M*/
141: #define SETERRMPI(comm,ierr,...) return (PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__),PETSC_MPI_ERROR_CODE)
143: /*MC
144: SETERRA - Fortran-only macro that can be called when an error has been detected from the main program
146: Synopsis:
147: #include <petscsys.h>
148: PetscErrorCode SETERRA(MPI_Comm comm,PetscErrorCode ierr,char *message)
150: Collective
152: Input Parameters:
153: + comm - A communicator, so that the error can be collective
154: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
155: - message - error message in the printf format
157: Level: beginner
159: Notes:
160: This should only be used with Fortran. With C/C++, use SETERRQ().
162: Fortran Notes:
163: SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the
164: Fortran main program.
166: .seealso: SETERRQ(), SETERRABORT(), PetscCall(), CHKERRA(), PetscCallAbort()
167: M*/
169: /*MC
170: SETERRABORT - Macro that can be called when an error has been detected,
172: Synopsis:
173: #include <petscsys.h>
174: PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message,...)
176: Collective
178: Input Parameters:
179: + comm - A communicator, so that the error can be collective
180: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
181: - message - error message in the printf format
183: Level: beginner
185: Notes:
186: This function just calls MPI_Abort().
188: .seealso: SETERRQ(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), PetscCall(), CHKMEMQ
189: M*/
190: #define SETERRABORT(comm,ierr,...) do { \
191: PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,__VA_ARGS__); \
192: MPI_Abort(comm,ierr); \
193: } while (0)
195: /*MC
198: Synopsis:
199: #include <petscerror.h>
202: Collective
204: Input Parameters:
205: + cond - The boolean condition
206: . comm - The communicator on which the check can be collective on
207: . ierr - A nonzero error code, see include/petscerror.h for the complete list
208: - message - Error message in printf format
210: Notes:
211: Enabled in both optimized and debug builds.
213: Calls SETERRQ() if the assertion fails, so can only be called from functions returning a
214: PetscErrorCode (or equivalent type after conversion).
216: Level: beginner
218: .seealso: PetscAssert(), SETERRQ(), PetscError(), PetscCall()
219: M*/
222: /*MC
225: Synopsis:
226: #include <petscerror.h>
229: Collective
231: Input Parameters:
232: + cond - The boolean condition
233: . comm - The communicator on which the check can be collective on
234: . ierr - A nonzero error code, see include/petscerror.h for the complete list
235: - message - Error message in printf format
237: Notes:
240: release.
242: Level: deprecated
245: M*/
248: /*MC
249: PetscAssert - Assert that a particular condition is true
251: Synopsis:
252: #include <petscerror.h>
253: void PetscAssert(bool cond, MPI_Comm comm, PetscErrorCode ierr, const char *message, ...)
255: Collective
257: Input Parameters:
258: + cond - The boolean condition
259: . comm - The communicator on which the check can be collective on
260: . ierr - A nonzero error code, see include/petscerror.h for the complete list
261: - message - Error message in printf format
263: Notes:
264: Enabled only in debug builds. Note that any arguments to this macros are still visible to the
265: compiler optimized builds (so must still contain valid code) but are guaranteed to not be
266: executed.
270: Level: beginner
273: M*/
274: #define PetscAssert(cond,comm,ierr,...) if (PetscUnlikelyDebug(!(cond))) SETERRQ(comm,ierr,__VA_ARGS__)
276: /*MC
277: PetscCall - Checks error code returned from a PETSc function, if non-zero it calls the error
278: handler and and returns from the current function.
280: Synopsis:
281: #include <petscerror.h>
282: void PetscCall(PetscErrorCode ierr)
284: Not Collective
286: Input Parameter:
287: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
289: Notes:
290: Once the error handler is called the calling function is then returned from with the given
291: error code. Experienced users can set the error handler with PetscPushErrorHandler().
293: PetscCall(ierr) is fundamentally a macro replacement for
294: .vb
295: if (ierr) return PetscError(...,ierr,...);
296: .ve
298: PetscCall() cannot be used in functions returning a datatype not convertible to
299: PetscErrorCode. For example, PetscCall() may not be used in functions returning void, use
300: PetscCallVoid() in this case.
302: Fortran Notes:
303: PetscCall() may be called from Fortran subroutines but CHKERRA() must be called from the
304: Fortran main program.
306: Example Usage:
307: .vb
308: PetscInitiailize(...); // OK to call even when PETSc is not yet initialized!
310: extern int foo(int);
312: foo(1); // OK if int is convertible to PetscErrorCode
314: struct my_struct
315: {
316: void *data;
317: } my_complex_type;
319: struct my_struct bar(void)
320: {
321: foo(15); // ERROR PetscErrorCode not convertible to struct my_struct!
322: }
324: PetscCall(bar()) // ERROR input not convertible to PetscErrorCode
325: .ve
327: Level: beginner
330: PetscPushErrorHandler(), PetscError(), CHKMEMQ, CHKERRA()
331: M*/
332: #if defined(PETSC_CLANG_STATIC_ANALYZER)
333: void PetscErrorCode;
334: void PetscErrorCode;
335: #else
336: #define PetscCall(...) do { \
337: PetscErrorCode ierr_q_ = __VA_ARGS__; \
338: if (PetscUnlikely(ierr_q_)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_q_,PETSC_ERROR_REPEAT," "); \
339: } while (0)
340: #define PetscCallVoid(...) do { \
341: PetscErrorCode ierr_void_ = __VA_ARGS__; \
342: if (PetscUnlikely(ierr_void_)) { \
343: (void)PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_void_,PETSC_ERROR_REPEAT," "); \
344: return; \
345: } \
346: } while (0)
347: #endif
349: /*MC
350: CHKERRQ - Checks error code returned from PETSc function
352: Synopsis:
353: #include <petscsys.h>
354: void CHKERRQ(PetscErrorCode ierr)
356: Not Collective
358: Input Parameters:
359: . ierr - nonzero error code
361: Notes:
362: Deprecated in favor of PetscCall(). This routine behaves identically to it.
364: Level: deprecated
366: .seealso: PetscCall()
367: M*/
368: #define CHKERRQ(...) PetscCall(__VA_ARGS__)
369: #define CHKERRV(...) PetscCallVoid(__VA_ARGS__)
371: /*MC
372: PetscCallMPI - Checks error code returned from MPI calls, if non-zero it calls the error
373: handler and then returns
375: Synopsis:
376: #include <petscerror.h>
377: void PetscCallMPI(PetscErrorCode ierr)
379: Not Collective
381: Input Parameters:
382: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
384: Notes:
385: Always returns the error code PETSC_ERR_MPI; the MPI error code and string are embedded in
386: the string error message. Do not use this to call any other routines (for example PETSc
387: routines), it should only be used for direct MPI calls. Due to limitations of the
388: preprocessor this can unfortunately not easily be enforced, so the user should take care to
389: check this themselves.
391: Example Usage:
392: .vb
393: MPI_Comm_size(...); // OK, calling MPI function
395: PetscFunction(...); // ERROR, use PetscCall() instead!
396: .ve
398: Level: beginner
400: .seealso: SETERRMPI(), PetscCall(), SETERRQ(), SETERRABORT(), PetscCallAbort(),
401: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKMEMQ
402: M*/
403: #if defined(PETSC_CLANG_STATIC_ANALYZER)
404: void PetscErrorCode;
405: #else
406: #define PetscCallMPI(...) do { \
407: PetscMPIInt _7_errorcode = __VA_ARGS__; \
408: if (PetscUnlikely(_7_errorcode)) { \
409: char _7_errorstring[MPI_MAX_ERROR_STRING]; \
410: PetscMPIInt _7_resultlen; \
411: MPI_Error_string(_7_errorcode,(char*)_7_errorstring,&_7_resultlen); \
412: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MPI,"MPI error %d %s Ignore the following value %d",(int)_7_errorcode,_7_errorstring,_7_resultlen); \
413: } \
414: } while (0)
415: #endif
417: /*MC
418: CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error
419: handler and then returns
421: Synopsis:
422: #include <petscerror.h>
423: void CHKERRMPI(PetscErrorCode ierr)
425: Not Collective
427: Input Parameter:
428: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
430: Notes:
431: Deprecated in favor of PetscCallMPI(). This routine behaves identically to it.
433: Level: deprecated
435: .seealso: PetscCallMPI()
436: M*/
437: #define CHKERRMPI(...) PetscCallMPI(__VA_ARGS__)
439: /*MC
440: PetscCallAbort - Checks error code returned from PETSc function, if non-zero it aborts immediately
442: Synopsis:
443: #include <petscerror.h>
444: void PetscCallAbort(MPI_Comm comm, PetscErrorCode ierr)
446: Collective on comm
448: Input Parameters:
449: + comm - the MPI communicator on which to abort
450: - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
452: Notes:
453: This macro has identical type and usage semantics to PetscCall() with the important caveat
454: that this macro does not return. Instead, if ierr is nonzero it calls the PETSc error handler
455: and then immediately calls MPI_Abort(). It can therefore be used anywhere.
457: As per MPI_Abort semantics the communicator passed must be valid, although there is currently
458: no attempt made at handling any potential errors from MPI_Abort(). Note that while
459: MPI_Abort() is required to terminate only those processes which reside on comm, it is often
460: the case that MPI_Abort() terminates *all* processes.
462: Example Usage:
463: .vb
464: PetscErrorCode boom(void) { return PETSC_ERR_MEM; }
466: void foo(void)
467: {
468: PETSC_COMM_WORLD,boom(); // OK, does not return a type
469: }
471: double bar(void)
472: {
473: PETSC_COMM_WORLD,boom(); // OK, does not return a type
474: }
476: MPI_COMM_NULL,boom(); // ERROR, communicator should be valid
478: struct baz
479: {
480: baz()
481: {
482: PETSC_COMM_SELF,boom(); // OK
483: }
485: ~baz()
486: {
487: PETSC_COMM_SELF,boom(); // OK (in fact the only way to handle PETSc errors)
488: }
489: };
490: .ve
492: Level: intermediate
494: .seealso: SETERRABORT(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(),
495: SETERRQ(), CHKMEMQ, PetscCallMPI()
496: M*/
497: #if defined(PETSC_CLANG_STATIC_ANALYZER)
498: void MPI_Comm,PetscErrorCode;
499: void PetscErrorCode;
500: #else
501: #define PetscCallAbort(comm,...) do { \
502: PetscErrorCode ierr_abort_ = __VA_ARGS__; \
503: if (PetscUnlikely(ierr_abort_)) { \
504: PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_abort_,PETSC_ERROR_REPEAT," "); \
505: MPI_Abort(comm,ierr_abort_); \
506: } \
507: } while (0)
508: #define PetscCallContinue(...) do { \
509: PetscErrorCode ierr_continue_ = __VA_ARGS__; \
510: if (PetscUnlikely(ierr_continue_)) PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_continue_,PETSC_ERROR_REPEAT," "); \
511: } while (0)
512: #endif
514: /*MC
515: CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately.
517: Synopsis:
518: #include <petscerror.h>
519: void CHKERRABORT(MPI_Comm comm, PetscErrorCode ierr)
521: Not Collective
523: Input Parameters:
524: + comm - the MPI communicator
525: - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
527: Notes:
528: Deprecated in favor of PetscCallAbort(). This routine behaves identically to it.
530: Level: deprecated
532: .seealso: PetscCallAbort()
533: M*/
534: #define CHKERRABORT(comm,...) PetscCallAbort(comm,__VA_ARGS__)
535: #define CHKERRCONTINUE(...) PetscCallContinue(__VA_ARGS__)
537: /*MC
538: CHKERRA - Fortran-only replacement for PetscCall in the main program, which aborts immediately
540: Synopsis:
541: #include <petscsys.h>
542: PetscErrorCode CHKERRA(PetscErrorCode ierr)
544: Not Collective
546: Input Parameters:
547: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
549: Level: beginner
551: Notes:
552: This should only be used with Fortran. With C/C++, use PetscCall() in normal usage,
553: or PetscCallAbort() if wanting to abort immediately on error.
555: Fortran Notes:
556: PetscCall() may be called from Fortran subroutines but CHKERRA() must be called from the
557: Fortran main program.
559: .seealso: PetscCall(), PetscCallAbort(), SETERRA(), SETERRQ(), SETERRABORT()
560: M*/
562: PETSC_EXTERN PetscErrorCode PetscAbortFindSourceFile_Private(const char*,PetscInt*);
563: PETSC_EXTERN PetscBool petscwaitonerrorflg;
564: PETSC_EXTERN PetscBool petscindebugger;
566: /*MC
567: PETSCABORT - Call MPI_Abort with an informative error code
569: Synopsis:
570: #include <petscsys.h>
571: PETSCABORT(MPI_Comm comm, PetscErrorCode ierr)
573: Collective
575: Input Parameters:
576: + comm - A communicator, so that the error can be collective
577: - ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
579: Level: advanced
581: Notes:
582: We pass MPI_Abort() an error code of format XX_YYYY_ZZZ, where XX, YYYY are an index and line number of the file
583: where PETSCABORT is called, respectively. ZZZ is the PETSc error code.
585: If XX is zero, this means that the call was made in the routine main().
586: 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[]
587: is out of date. PETSc developers have to update it.
588: 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.
590: If the option -start_in_debugger was used then this calls abort() to stop the program in the debugger.
592: M*/
593: #define PETSCABORT(comm,...) do { \
594: if (petscwaitonerrorflg) PetscSleep(1000); \
595: if (petscindebugger) abort(); \
596: else { \
597: PetscErrorCode ierr_petsc_abort_ = __VA_ARGS__; \
598: PetscInt idx = 0; \
599: PetscAbortFindSourceFile_Private(__FILE__,&idx); \
600: MPI_Abort(comm,(PetscMPIInt)(0*idx*10000000 + 0*__LINE__*1000 + ierr_petsc_abort_)); \
601: } \
602: } while (0)
604: #ifdef PETSC_CLANGUAGE_CXX
605: /*MC
606: PetscCallThrow - Checks error code, if non-zero it calls the C++ error handler which throws
607: an exception
609: Synopsis:
610: #include <petscerror.h>
611: void PetscCallThrow(PetscErrorCode ierr)
613: Not Collective
615: Input Parameter:
616: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
618: Notes:
619: Requires PETSc to be configured with clanguage = c++. Throws a std::runtime_error() on error.
621: Once the error handler throws the exception you can use PetscCallVoid() which returns without
622: an error code (bad idea since the error is ignored) or PetscCallAbort() to have MPI_Abort()
623: called immediately.
625: Level: beginner
627: .seealso: SETERRQ(), PetscCall(), SETERRABORT(), PetscCallAbort(), PetscTraceBackErrorHandler(),
628: PetscPushErrorHandler(), PetscError(), CHKMEMQ
629: M*/
630: #define PetscCallThrow(...) do { \
631: PetscErrorCode ierr_cxx_ = __VA_ARGS__; \
632: if (PetscUnlikely(ierr_cxx_)) PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr_cxx_,PETSC_ERROR_IN_CXX,PETSC_NULLPTR); \
633: } while (0)
635: /*MC
636: CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception
638: Synopsis:
639: #include <petscerror.h>
640: void CHKERRXX(PetscErrorCode ierr)
642: Not Collective
644: Input Parameter:
645: . ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
647: Notes:
648: Deprecated in favor of PetscCallThrow(). This routine behaves identically to it.
650: Level: deprecated
652: .seealso: PetscCallThrow()
653: M*/
654: #define CHKERRXX(...) PetscCallThrow(__VA_ARGS__)
655: #endif
657: /*MC
658: PetscCallCXX - Checks C++ function calls and if they throw an exception, catch it and then
659: return a PETSc error code
661: Synopsis:
662: #include <petscerror.h>
663: void PetscCallCXX(expr) noexcept;
665: Not Collective
667: Input Parameter:
668: . expr - An arbitrary expression
670: Notes:
671: PetscCallCXX(expr) is a macro replacement for
672: .vb
673: try {
674: expr;
675: } catch (const std::exception& e) {
676: return ConvertToPetscErrorCode(e);
677: }
678: .ve
679: Due to the fact that it catches any (reasonable) exception, it is essentially noexcept.
681: Example Usage:
682: .vb
683: void foo(void) { throw std::runtime_error("error"); }
685: void bar()
686: {
687: foo(); // ERROR bar() does not return PetscErrorCode
688: }
690: PetscErrorCode baz()
691: {
692: foo(); // OK
694: PetscCallCXX(
695: bar();
696: foo(); // OK mutliple statements allowed
697: );
698: }
700: struct bop
701: {
702: bop()
703: {
704: foo(); // ERROR returns PetscErrorCode, cannot be used in constructors
705: }
706: };
708: // ERROR contains do-while, cannot be used as function-try block
709: PetscErrorCode qux() PetscCallCXX(
710: bar();
711: baz();
712: foo();
713: return 0;
714: )
715: .ve
717: Level: beginner
719: .seealso: PetscCallThrow(), SETERRQ(), PetscCall(), SETERRABORT(), PetscCallAbort(),
720: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKMEMQ
721: M*/
722: #define PetscCallCXX(...) do { \
723: try { \
724: __VA_ARGS__; \
725: } catch (const std::exception& e) { \
726: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"%s",e.what()); \
727: } \
728: } while (0)
730: /*MC
731: CHKERRCXX - Checks C++ function calls and if they throw an exception, catch it and then
732: return a PETSc error code
734: Synopsis:
735: #include <petscerror.h>
736: void CHKERRCXX(func) noexcept;
738: Not Collective
740: Input Parameter:
741: . func - C++ function calls
743: Notes:
744: Deprecated in favor of PetscCallCXX(). This routine behaves identically to it.
746: Level: deprecated
748: .seealso: PetscCallCXX()
749: M*/
750: #define CHKERRCXX(...) PetscCallCXX(__VA_ARGS__)
752: /*MC
753: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
755: Synopsis:
756: #include <petscsys.h>
757: CHKMEMQ;
759: Not Collective
761: Level: beginner
763: Notes:
764: We highly recommend using Valgrind https://petsc.org/release/faq/#valgrind or for NVIDIA CUDA systems
765: https://docs.nvidia.com/cuda/cuda-memcheck/index.html for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that
766: do not have valgrind, but is not as good as valgrind or cuda-memcheck.
768: Must run with the option -malloc_debug (-malloc_test in debug mode; or if PetscMallocSetDebug() called) to enable this option
770: Once the error handler is called the calling function is then returned from with the given error code.
772: By defaults prints location where memory that is corrupted was allocated.
774: Use CHKMEMA for functions that return void
776: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), PetscMallocValidate()
777: M*/
778: #if defined(PETSC_CLANG_STATIC_ANALYZER)
779: #define CHKMEMQ
780: #define CHKMEMA
781: #else
782: #define CHKMEMQ PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);
783: #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__)
784: #endif
786: /*E
787: PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers
789: Level: advanced
791: PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated
793: Developer Notes:
794: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler()
796: .seealso: PetscError(), SETERRXX()
797: E*/
798: typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;
800: #if defined(__clang_analyzer__)
801: __attribute__((analyzer_noreturn))
802: #endif
803: PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...) PETSC_ATTRIBUTE_COLD PETSC_ATTRIBUTE_FORMAT(7,8);
805: PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
806: PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
807: PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
808: PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
809: PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
810: PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
811: PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
812: PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
813: PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*) PETSC_ATTRIBUTE_COLD;
814: PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*);
815: PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
816: PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*);
817: PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
818: PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);
820: PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void);
821: PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") static inline void PetscSignalSegvCheckPointer(void) {PetscSignalSegvCheckPointerOrMpi();}
823: /*MC
824: PetscErrorPrintf - Prints error messages.
826: Synopsis:
827: #include <petscsys.h>
828: PetscErrorCode (*PetscErrorPrintf)(const char format[],...);
830: Not Collective
832: Input Parameter:
833: . format - the usual printf() format string
835: Options Database Keys:
836: + -error_output_stdout - cause error messages to be printed to stdout instead of the (default) stderr
837: - -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.)
839: Notes:
840: Use
841: $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
842: $ error is handled.) and
843: $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function
845: Use
846: PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
847: PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file.
849: Use
850: PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print
852: Level: developer
854: Fortran Note:
855: This routine is not supported in Fortran.
857: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscPushErrorHandler(), PetscVFPrintf(), PetscHelpPrintf()
858: M*/
859: PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...) PETSC_ATTRIBUTE_FORMAT(1,2);
861: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
862: PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
863: PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
864: PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);
865: PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void);
867: /*
868: Allows the code to build a stack frame as it runs
869: */
871: #if defined(PETSC_USE_DEBUG)
872: #define PETSCSTACKSIZE 64
873: typedef struct {
874: const char *function[PETSCSTACKSIZE];
875: const char *file[PETSCSTACKSIZE];
876: int line[PETSCSTACKSIZE];
877: int petscroutine[PETSCSTACKSIZE]; /* 0 external called from petsc, 1 petsc functions, 2 petsc user functions */
878: int currentsize;
879: int hotdepth;
880: PetscBool check; /* runtime option to check for correct Push/Pop semantics at runtime */
881: } PetscStack;
882: PETSC_EXTERN PetscStack petscstack;
883: #else
884: typedef struct {
885: char Silence_empty_struct_has_size_0_in_C_size_1_in_Cpp;
886: } PetscStack;
887: #endif
889: #if defined(PETSC_SERIALIZE_FUNCTIONS)
890: #include <petsc/private/petscfptimpl.h>
891: /*
892: Registers the current function into the global function pointer to function name table
894: Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
895: */
896: #define PetscRegister__FUNCT__() do { \
897: static PetscBool __chked = PETSC_FALSE; \
898: if (!__chked) {\
899: void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\
900: __chked = PETSC_TRUE;\
901: }} while (0)
902: #else
903: #define PetscRegister__FUNCT__()
904: #endif
906: #if defined(PETSC_CLANG_STATIC_ANALYZER)
907: #define PetscStackPushNoCheck(funct,petsc_routine,hot)
908: #define PetscStackPopNoCheck
909: #define PetscStackClearTop
913: #define return a return a
914: #define return return
915: #define PetscStackPop
916: #define PetscStackPush(f)
917: #elif defined(PETSC_USE_DEBUG)
918: /* Stack handling is based on the following two "NoCheck" macros. These should only be called directly by other error
919: * handling macros. We record the line of the call, which may or may not be the location of the definition. But is at
920: * least more useful than "unknown" because it can distinguish multiple calls from the same function.
921: */
922: #define PetscStackPushNoCheck(funct,petsc_routine,hot) do { \
923: PetscStackSAWsTakeAccess(); \
924: if (petscstack.currentsize < PETSCSTACKSIZE) { \
925: petscstack.function[petscstack.currentsize] = funct; \
926: petscstack.file[petscstack.currentsize] = __FILE__; \
927: petscstack.line[petscstack.currentsize] = __LINE__; \
928: petscstack.petscroutine[petscstack.currentsize] = petsc_routine; \
929: } \
930: ++petscstack.currentsize; \
931: petscstack.hotdepth += (hot || petscstack.hotdepth); \
932: PetscStackSAWsGrantAccess(); \
933: } while (0)
935: #define PetscStackPopNoCheck(funct) do { \
936: PetscStackSAWsTakeAccess(); \
937: if (PetscUnlikely(petscstack.currentsize <= 0)) { \
938: if (PetscUnlikely(petscstack.check)) { \
939: printf("Invalid stack size %d, pop %s\n",petscstack.currentsize,funct); \
940: } \
941: } else { \
942: if (--petscstack.currentsize < PETSCSTACKSIZE) { \
943: if (PetscUnlikely( \
944: petscstack.check && \
945: petscstack.petscroutine[petscstack.currentsize] && \
946: (petscstack.function[petscstack.currentsize] != \
947: (const char*)funct))) { \
948: /* We need this string comparison because "unknown" can be defined in different static strings: */ \
949: PetscBool _cmpflg; \
950: const char *_funct = petscstack.function[petscstack.currentsize]; \
951: PetscStrcmp(_funct,funct,&_cmpflg); \
952: if (!_cmpflg) printf("Invalid stack: push from %s, pop from %s\n", _funct,funct); \
953: } \
954: petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \
955: petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \
956: petscstack.line[petscstack.currentsize] = 0; \
957: petscstack.petscroutine[petscstack.currentsize] = 0; \
958: } \
959: petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \
960: } \
961: PetscStackSAWsGrantAccess(); \
962: } while (0)
964: #define PetscStackClearTop do { \
965: PetscStackSAWsTakeAccess(); \
966: if (petscstack.currentsize > 0 && \
967: --petscstack.currentsize < PETSCSTACKSIZE) { \
968: petscstack.function[petscstack.currentsize] = PETSC_NULLPTR; \
969: petscstack.file[petscstack.currentsize] = PETSC_NULLPTR; \
970: petscstack.line[petscstack.currentsize] = 0; \
971: petscstack.petscroutine[petscstack.currentsize] = 0; \
972: } \
973: petscstack.hotdepth = PetscMax(petscstack.hotdepth-1,0); \
974: PetscStackSAWsGrantAccess(); \
975: } while (0)
977: /*MC
979: line of PETSc functions should be return 0;
981: Synopsis:
982: #include <petscsys.h>
984: Not Collective
986: Usage:
987: .vb
988: int something;
990: .ve
992: Notes:
995: Not available in Fortran
997: Level: developer
1001: M*/
1003: PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_FALSE); \
1004: PetscRegister__FUNCT__(); \
1005: } while (0)
1007: /*MC
1009: performance-critical circumstances. Use of this function allows for lighter profiling by default.
1011: Synopsis:
1012: #include <petscsys.h>
1015: Not Collective
1017: Usage:
1018: .vb
1019: int something;
1022: .ve
1024: Notes:
1025: Not available in Fortran
1027: Level: developer
1031: M*/
1033: PetscStackPushNoCheck(PETSC_FUNCTION_NAME,1,PETSC_TRUE); \
1034: PetscRegister__FUNCT__(); \
1035: } while (0)
1037: /*MC
1040: Synopsis:
1041: #include <petscsys.h>
1044: Not Collective
1046: Usage:
1047: .vb
1048: int something;
1051: .ve
1053: Notes:
1054: Final line of PETSc functions should be return 0 except for main().
1056: Not available in Fortran
1059: routine instead of as a PETSc library routine.
1061: Level: intermediate
1065: M*/
1067: PetscStackPushNoCheck(PETSC_FUNCTION_NAME,2,PETSC_FALSE); \
1068: PetscRegister__FUNCT__(); \
1069: } while (0)
1071: #define PetscStackPush(n) do { \
1072: PetscStackPushNoCheck(n,0,PETSC_FALSE); \
1073: CHKMEMQ; \
1074: } while (0)
1076: #define PetscStackPop do { \
1077: CHKMEMQ; \
1078: PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1079: } while (0)
1081: /*MC
1082: PetscFunctionReturn - Last executable line of each PETSc function
1083: used for error handling. Replaces return()
1085: Synopsis:
1086: #include <petscsys.h>
1087: void return 0;
1089: Not Collective
1091: Usage:
1092: .vb
1093: ....
1094: return 0;
1095: }
1096: .ve
1098: Notes:
1099: Not available in Fortran
1101: Level: developer
1105: M*/
1106: #define return a do { \
1107: PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1108: return a; \
1109: } while (0)
1111: #define return do { \
1112: PetscStackPopNoCheck(PETSC_FUNCTION_NAME); \
1113: return; \
1114: } while (0)
1115: #else /* PETSC_USE_DEBUG */
1116: #define PetscStackPushNoCheck(funct,petsc_routine,hot)
1117: #define PetscStackPopNoCheck
1118: #define PetscStackClearTop
1122: #define return a return a
1123: #define return return
1124: #define PetscStackPop CHKMEMQ
1125: #define PetscStackPush(f) CHKMEMQ
1126: #endif /* PETSC_USE_DEBUG */
1128: #if defined(PETSC_CLANG_STATIC_ANALYZER)
1129: #define PetscStackCall(name,routine)
1130: #define PetscStackCallStandard(func,...)
1131: #else
1132: /*
1133: PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.
1135: Input Parameters:
1136: + name - string that gives the name of the function being called
1137: - routine - actual call to the routine, including and ierr;
1139: Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes
1141: 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.
1143: */
1144: #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while (0)
1146: /*
1147: PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack.
1149: Input Parameters:
1150: + func- name of the routine
1151: - args - arguments to the routine surrounded by ()
1153: Notes:
1154: This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not.
1156: Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc.
1158: */
1159: #define PetscStackCallStandard(func,...) do { \
1160: PetscStackPush(PetscStringize(func)); \
1161: PetscErrorCode __func(__VA_ARGS__); \
1162: PetscStackPop; \
1164: } while (0)
1165: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1167: #endif