Actual source code: petscerror.h
1: /*
2: Contains all error handling interfaces for PETSc.
3: */
6: #include petsc.h
9: /*
10: Defines the directory where the compiled source is located; used
11: in printing error messages. Each makefile has an entry
12: LOCDIR = thedirectory
13: and bmake/common_variables includes in CCPPFLAGS -D__SDIR__='"${LOCDIR}"'
14: which is a flag passed to the C/C++ compilers. This declaration below
15: is only needed if some code is compiled without the -D__SDIR__
16: */
19: #endif
21: /*
22: Defines the function where the compiled source is located; used
23: in printing error messages. This is defined here in case the user
24: does not declare it.
25: */
28: #endif
30: /*
31: These are the generic error codes. These error codes are used
32: many different places in the PETSc source code. The string versions are
33: at src/sys/error/err.c any changes here must also be made there
34: These are also define in include/finclude/petscerror.h any CHANGES here
35: must be also made there.
37: */
38: #define PETSC_ERR_MIN_VALUE 54 /* should always be one less then the smallest value */
40: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
41: #define PETSC_ERR_SUP 56 /* no support for requested operation */
42: #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */
43: #define PETSC_ERR_ORDER 58 /* operation done in wrong order */
44: #define PETSC_ERR_SIG 59 /* signal received */
45: #define PETSC_ERR_FP 72 /* floating point exception */
46: #define PETSC_ERR_COR 74 /* corrupted PETSc object */
47: #define PETSC_ERR_LIB 76 /* error in library called by PETSc */
48: #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */
49: #define PETSC_ERR_MEMC 78 /* memory corruption */
50: #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */
51: #define PETSC_ERR_USER 83 /* user has not provided needed function */
53: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
54: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
55: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
56: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
57: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
58: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
59: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
60: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
61: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
62: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
63: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
64: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */
65: #define PETSC_ERR_ARG_DOMAIN 87 /* argument is not in domain of function */
67: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
68: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
69: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
70: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
72: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
73: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
75: #define PETSC_ERR_MAX_VALUE 88 /* this is always the one more than the largest error code */
77: #if defined(PETSC_USE_ERRORCHECKING)
79: /*MC
80: SETERRQ - Macro that is called when an error has been detected,
82: Not Collective
84: Synopsis:
85: void SETERRQ(PetscErrorCode errorcode,char *message)
88: Input Parameters:
89: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
90: - message - error message
92: Level: beginner
94: Notes:
95: Once the error handler is called the calling function is then returned from with the given error code.
97: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
100: Experienced users can set the error handler with PetscPushErrorHandler().
102: Concepts: error^setting condition
104: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
105: M*/
106: #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}
108: /*MC
109: SETERRQ1 - Macro that is called when an error has been detected,
111: Not Collective
113: Synopsis:
114: void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)
117: Input Parameters:
118: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
119: . message - error message in the printf format
120: - arg - argument (for example an integer, string or double)
122: Level: beginner
124: Notes:
125: Once the error handler is called the calling function is then returned from with the given error code.
127: Experienced users can set the error handler with PetscPushErrorHandler().
129: Concepts: error^setting condition
131: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
132: M*/
133: #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}
135: /*MC
136: SETERRQ2 - Macro that is called when an error has been detected,
138: Not Collective
140: Synopsis:
141: void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)
144: Input Parameters:
145: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
146: . message - error message in the printf format
147: . arg1 - argument (for example an integer, string or double)
148: - arg2 - argument (for example an integer, string or double)
150: Level: beginner
152: Notes:
153: Once the error handler is called the calling function is then returned from with the given error code.
155: Experienced users can set the error handler with PetscPushErrorHandler().
157: Concepts: error^setting condition
159: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
160: M*/
161: #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}
163: /*MC
164: SETERRQ3 - Macro that is called when an error has been detected,
166: Not Collective
168: Synopsis:
169: void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)
172: Input Parameters:
173: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
174: . message - error message in the printf format
175: . arg1 - argument (for example an integer, string or double)
176: . arg2 - argument (for example an integer, string or double)
177: - arg3 - argument (for example an integer, string or double)
179: Level: beginner
181: Notes:
182: Once the error handler is called the calling function is then returned from with the given error code.
184: There are also versions for 4, 5, 6 and 7 arguments.
186: Experienced users can set the error handler with PetscPushErrorHandler().
188: Concepts: error^setting condition
190: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
191: M*/
192: #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);}
194: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
195: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
196: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6);}
197: #define SETERRQ7(n,s,a1,a2,a3,a4,a5,a6,a7) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6,a7);}
198: #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}
200: /*MC
201: CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
203: Not Collective
205: Synopsis:
206: void CHKERRQ(PetscErrorCode errorcode)
209: Input Parameters:
210: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
212: Level: beginner
214: Notes:
215: Once the error handler is called the calling function is then returned from with the given error code.
217: Experienced users can set the error handler with PetscPushErrorHandler().
219: CHKERRQ(n) is fundamentally a macro replacement for
220: if (n) return(PetscError(...,n,...));
222: Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
223: highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
224: it cannot be used in functions which return(void) or any other datatype. In these types of functions,
225: a more appropriate construct for using PETSc Error Handling would be
226: if (n) {PetscError(....); return(YourReturnType);}
228: Concepts: error^setting condition
230: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
231: M*/
232: #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
234: #define CHKERRV(n) if (n) {n = PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");return;}
235: #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
236: #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
238: #define CHKFPQ(f) if (f != f) {SETERRQ(PETSC_ERR_FP, "Invalid value: NaN");}
240: /*MC
241: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
243: Not Collective
245: Synopsis:
246: CHKMEMQ;
248: Level: beginner
250: Notes:
251: Must run with the option -malloc_debug to enable this option
253: Once the error handler is called the calling function is then returned from with the given error code.
255: By defaults prints location where memory that is corrupted was allocated.
257: Use CHKMEMA for functions that return void
259: Concepts: memory corruption
261: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
262: PetscMallocValidate()
263: M*/
264: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}
266: #define CHKMEMA {PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);}
268: #if defined(PETSC_UNDERSCORE_CHKERR)
270: #define _ __g
272: #endif
274: #define PETSC_EXCEPTIONS_MAX 256
280: EXTERN PetscErrorCode PetscExceptionPush(PetscErrorCode);
281: EXTERN void PetscExceptionPop(PetscErrorCode);
283: EXTERN PetscErrorCode PetscErrorSetCatchable(PetscErrorCode,PetscTruth);
284: EXTERN PetscTruth PetscErrorIsCatchable(PetscErrorCode);
285: /*MC
286: PetscExceptionCaught - Indicates if a specific exception zierr was caught.
288: Not Collective
290: Synopsis:
291: PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);
293: Input Parameters:
294: + xierr - error code returned from PetscExceptionTry1()
295: - zierr - error code you want it to be
297: Level: advanced
299: Notes:
300: PETSc must not be configured using the option --with-errorchecking=0 for this to work
302: Use PetscExceptionValue() to see if the current error code is one that has been "tried"
304: Concepts: exceptions, exception hanlding
306: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
307: CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
308: M*/
309: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
310: PetscInt i;
311: if (xierr != zierr) return PETSC_FALSE;
312: for (i=0; i<PetscErrorUncatchableCount; i++) {
313: if (PetscErrorUncatchable[i] == zierr) {
314: return PETSC_FALSE;
315: }
316: }
317: return PETSC_TRUE;
318: }
320: /*MC
321: PetscExceptionValue - Indicates if the error code is one that is currently being tried
323: Not Collective
325: Synopsis:
326: PetscTruth PetscExceptionValue(PetscErrorCode xierr);
328: Input Parameters:
329: . xierr - error code
331: Level: developer
333: Notes:
334: PETSc must not be configured using the option --with-errorchecking=0 for this to work
336: Use PetscExceptionCaught() to see if the current error code is EXACTLY the one you want
338: Concepts: exceptions, exception hanlding
340: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
341: CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
342: M*/
343: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) {
344: PetscInt i;
345: for (i=0; i<PetscExceptionsCount; i++) {
346: if (PetscExceptions[i] == zierr) {
347: return PETSC_TRUE;
348: }
349: }
350: return PETSC_FALSE;
351: }
353: /*MC
354: PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception,
355: rather than an error. That is if that error code is treated the program returns to this level,
356: but does not call the error handlers
358: Not Collective
360: Synopsis:
361: PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);
363: Level: advanced
365: Notes:
366: PETSc must not be configured using the option --with-errorchecking=0 for this to work
368: Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in
369: PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example
370: of how the local try is ignored if a higher (in the stack) one is also in effect.
372: Concepts: exceptions, exception hanlding
374: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
375: CHKERRQ(), PetscExceptionCaught(), PetscExceptionPush(), PetscExceptionPop()
376: M*/
378: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)
380: #else
382: /*
383: These are defined to be empty for when error checking is turned off, with config/configure.py --with-errorchecking=0
384: */
386: #define SETERRQ(n,s) ;
387: #define SETERRQ1(n,s,a1) ;
388: #define SETERRQ2(n,s,a1,a2) ;
389: #define SETERRQ3(n,s,a1,a2,a3) ;
390: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
391: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
392: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
393: #define SETERRABORT(comm,n,s) ;
395: #define CHKERRQ(n) ;
396: #define CHKERRABORT(comm,n) ;
397: #define CHKERRCONTINUE(n) ;
399: #define CHKMEMQ ;
401: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
402: #define _
404: #endif
406: #define PetscErrorSetCatchable(a,b) 0
407: #define PetscExceptionCaught(a,b) PETSC_FALSE
408: #define PetscExceptionValue(a) PETSC_FALSE
409: #define PetscExceptionTry1(a,b) a
410: #endif
412: EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
413: EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
414: EXTERN PetscErrorCode PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
415: EXTERN PetscErrorCode PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
416: EXTERN PetscErrorCode PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
417: EXTERN PetscErrorCode PetscMPIAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
418: EXTERN PetscErrorCode PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
419: EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
420: EXTERN PetscErrorCode PetscReturnErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
421: EXTERN PetscErrorCode PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
422: EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
423: EXTERN PetscErrorCode PetscPopErrorHandler(void);
424: EXTERN PetscErrorCode PetscDefaultSignalHandler(int,void*);
425: EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
426: EXTERN PetscErrorCode PetscPopSignalHandler(void);
428: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
429: EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
431: /*
432: Allows the code to build a stack frame as it runs
433: */
434: #if defined(PETSC_USE_DEBUG)
436: #define PETSCSTACKSIZE 15
438: typedef struct {
439: const char *function[PETSCSTACKSIZE];
440: const char *file[PETSCSTACKSIZE];
441: const char *directory[PETSCSTACKSIZE];
442: int line[PETSCSTACKSIZE];
443: int currentsize;
444: } PetscStack;
447: EXTERN PetscErrorCode PetscStackCopy(PetscStack*,PetscStack*);
448: EXTERN PetscErrorCode PetscStackPrint(PetscStack*,FILE* fp);
450: #define PetscStackActive (petscstack != 0)
453: /*MC
455: used for error handling.
457: Synopsis:
460: Usage:
461: .vb
462: int something;
465: .ve
467: Notes:
468: Not available in Fortran
470: Level: developer
472: .seealso: PetscFunctionReturn()
474: .keywords: traceback, error handling
475: M*/
477: {\
478: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
479: petscstack->function[petscstack->currentsize] = __FUNCT__; \
480: petscstack->file[petscstack->currentsize] = __FILE__; \
481: petscstack->directory[petscstack->currentsize] = __SDIR__; \
482: petscstack->line[petscstack->currentsize] = __LINE__; \
483: petscstack->currentsize++; \
484: }}
486: #define PetscStackPush(n) \
487: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
488: petscstack->function[petscstack->currentsize] = n; \
489: petscstack->file[petscstack->currentsize] = "unknown"; \
490: petscstack->directory[petscstack->currentsize] = "unknown"; \
491: petscstack->line[petscstack->currentsize] = 0; \
492: petscstack->currentsize++; \
493: }}
495: #define PetscStackPop \
496: {if (petscstack && petscstack->currentsize > 0) { \
497: petscstack->currentsize--; \
498: petscstack->function[petscstack->currentsize] = 0; \
499: petscstack->file[petscstack->currentsize] = 0; \
500: petscstack->directory[petscstack->currentsize] = 0; \
501: petscstack->line[petscstack->currentsize] = 0; \
502: }};
504: /*MC
505: PetscFunctionReturn - Last executable line of each PETSc function
506: used for error handling. Replaces return()
508: Synopsis:
509: void return(0);
511: Usage:
512: .vb
513: ....
514: return(0);
515: }
516: .ve
518: Notes:
519: Not available in Fortran
521: Level: developer
525: .keywords: traceback, error handling
526: M*/
527: #define PetscFunctionReturn(a) \
528: {\
529: PetscStackPop; \
530: return(a);}
532: #define PetscFunctionReturnVoid() \
533: {\
534: PetscStackPop; \
535: return;}
538: #else
541: #define PetscFunctionReturn(a) return(a)
542: #define PetscFunctionReturnVoid() return
543: #define PetscStackPop
544: #define PetscStackPush(f)
545: #define PetscStackActive 0
547: #endif
549: EXTERN PetscErrorCode PetscStackCreate(void);
550: EXTERN PetscErrorCode PetscStackView(PetscViewer);
551: EXTERN PetscErrorCode PetscStackDestroy(void);
552: EXTERN PetscErrorCode PetscStackPublish(void);
553: EXTERN PetscErrorCode PetscStackDepublish(void);
557: #endif