Actual source code: petscerror.h
1: /*
2: Contains all error handling code 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.
15: */
18: #endif
20: /*
21: Defines the function where the compiled source is located; used
22: in printing error messages.
23: */
26: #endif
28: /*
29: These are the generic error codes. These error codes are used
30: many different places in the PETSc source code. The string versions are
31: at src/sys/src/error/err.c any changes here must also be made there
33: */
34: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
35: #define PETSC_ERR_MEM_MALLOC_0 85 /* cannot malloc zero size */
36: #define PETSC_ERR_SUP 56 /* no support for requested operation */
37: #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */
38: #define PETSC_ERR_ORDER 58 /* operation done in wrong order */
39: #define PETSC_ERR_SIG 59 /* signal received */
40: #define PETSC_ERR_FP 72 /* floating point exception */
41: #define PETSC_ERR_COR 74 /* corrupted PETSc object */
42: #define PETSC_ERR_LIB 76 /* error in library called by PETSc */
43: #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */
44: #define PETSC_ERR_MEMC 78 /* memory corruption */
45: #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */
46: #define PETSC_ERR_USER 83 /* user has not provided needed function */
48: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
49: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
50: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
51: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
52: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
53: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
54: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
55: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
56: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
57: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
58: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
59: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */
60: #define PETSC_ERR_ARG_DOMAIN 87 /* argument is not in domain of function */
62: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
63: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
64: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
65: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
67: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
68: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
70: #if defined(PETSC_USE_ERRORCHECKING)
72: /*MC
73: SETERRQ - Macro that is called when an error has been detected,
75: Not Collective
77: Synopsis:
78: void SETERRQ(PetscErrorCode errorcode,char *message)
81: Input Parameters:
82: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
83: - message - error message
85: Level: beginner
87: Notes:
88: Once the error handler is called the calling function is then returned from with the given error code.
90: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
93: Experienced users can set the error handler with PetscPushErrorHandler().
95: Concepts: error^setting condition
97: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
98: M*/
99: #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}
101: /*MC
102: SETERRQ1 - Macro that is called when an error has been detected,
104: Not Collective
106: Synopsis:
107: void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)
110: Input Parameters:
111: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
112: . message - error message in the printf format
113: - arg - argument (for example an integer, string or double)
115: Level: beginner
117: Notes:
118: Once the error handler is called the calling function is then returned from with the given error code.
120: Experienced users can set the error handler with PetscPushErrorHandler().
122: Concepts: error^setting condition
124: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
125: M*/
126: #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}
128: /*MC
129: SETERRQ2 - Macro that is called when an error has been detected,
131: Not Collective
133: Synopsis:
134: void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)
137: Input Parameters:
138: + errorcode - 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)
143: Level: beginner
145: Notes:
146: Once the error handler is called the calling function is then returned from with the given error code.
148: Experienced users can set the error handler with PetscPushErrorHandler().
150: Concepts: error^setting condition
152: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
153: M*/
154: #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}
156: /*MC
157: SETERRQ3 - Macro that is called when an error has been detected,
159: Not Collective
161: Synopsis:
162: void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)
165: Input Parameters:
166: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
167: . message - error message in the printf format
168: . arg1 - argument (for example an integer, string or double)
169: . arg2 - argument (for example an integer, string or double)
170: - arg3 - argument (for example an integer, string or double)
172: Level: beginner
174: Notes:
175: Once the error handler is called the calling function is then returned from with the given error code.
177: Experienced users can set the error handler with PetscPushErrorHandler().
179: Concepts: error^setting condition
181: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
182: M*/
183: #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);}
185: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
186: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
187: #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);}
188: #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);}
189: #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}
191: /*MC
192: CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
194: Not Collective
196: Synopsis:
197: void CHKERRQ(PetscErrorCode errorcode)
200: Input Parameters:
201: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
203: Level: beginner
205: Notes:
206: Once the error handler is called the calling function is then returned from with the given error code.
208: Experienced users can set the error handler with PetscPushErrorHandler().
210: CHKERRQ(n) is fundamentally a macro replacement for
211: if (n) return(PetscError(...,n,...));
213: Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
214: highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
215: it cannot be used in functions which return(void) or any other datatype. In these types of functions,
216: a more appropriate construct for using PETSc Error Handling would be
217: if (n) {PetscError(....); return(YourReturnType);}
219: Concepts: error^setting condition
221: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
222: M*/
223: #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
225: #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
226: #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
228: /*MC
229: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
231: Not Collective
233: Synopsis:
234: CHKMEMQ;
236: Level: beginner
238: Notes:
239: Must run with the option -malloc_debug to enable this option
241: Once the error handler is called the calling function is then returned from with the given error code.
243: By defaults prints location where memory that is corrupted was allocated.
245: Concepts: memory corruption
247: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
248: PetscMallocValidate()
249: M*/
250: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}
252: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
254: #define _ __g
256: #endif
258: #define PETSC_EXCEPTIONS_MAX 256
264: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode);
265: EXTERN void PETSC_DLLEXPORT PetscExceptionPop(PetscErrorCode);
267: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorSetCatchable(PetscErrorCode,PetscTruth);
269: /*MC
270: PetscExceptionCaught - Indicates if exception zierr was caught.
272: Not Collective
274: Synopsis:
275: PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);
277: Input Parameters:
278: + xierr - error code returned from PetscExceptionTry1()
279: - zierr - error code you want it to be
281: Level: advanced
283: Notes:
284: PETSc must not be configured using the option --with-errorchecking=0 for this to work
286: Concepts: exceptions, exception hanlding
288: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
289: CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
290: M*/
291: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
292: PetscInt i;
293: if (xierr != zierr) return PETSC_FALSE;
294: for (i=0; i<PetscErrorUncatchableCount; i++) {
295: if (PetscErrorUncatchable[i] == zierr) {
296: return PETSC_FALSE;
297: }
298: }
299: return PETSC_TRUE;
300: }
302: /*MC
303: PetscExceptionValue - Indicates if the error code is one that is currently being tried
305: Not Collective
307: Synopsis:
308: PetscTruth PetscExceptionValue(PetscErrorCode xierr);
310: Input Parameters:
311: . xierr - error code
313: Level: developer
315: Notes:
316: PETSc must not be configured using the option --with-errorchecking=0 for this to work
318: Concepts: exceptions, exception hanlding
320: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
321: CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
322: M*/
323: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) {
324: PetscInt i;
325: for (i=0; i<PetscExceptionsCount; i++) {
326: if (PetscExceptions[i] == zierr) {
327: return PETSC_TRUE;
328: }
329: }
330: return PETSC_FALSE;
331: }
333: /*MC
334: PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception,
335: rather than an error. That is if that error code is treated the program returns to this level,
336: but does not call the error handlers
338: Not Collective
340: Synopsis:
341: PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);
343: Level: advanced
345: Notes:
346: PETSc must not be configured using the option --with-errorchecking=0 for this to work
348: Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in
349: PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example
350: of how the local try is ignored if a higher (in the stack) one is also in effect.
352: Concepts: exceptions, exception hanlding
354: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
355: CHKERRQ(), PetscExceptionCaught()
356: M*/
358: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)
360: #else
361: #define SETERRQ(n,s) ;
362: #define SETERRQ1(n,s,a1) ;
363: #define SETERRQ2(n,s,a1,a2) ;
364: #define SETERRQ3(n,s,a1,a2,a3) ;
365: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
366: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
367: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
368: #define SETERRABORT(comm,n,s) ;
370: #define CHKERRQ(n) ;
371: #define CHKERRABORT(comm,n) ;
372: #define CHKERRCONTINUE(n) ;
374: #define CHKMEMQ ;
376: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
377: #define _
379: #endif
381: #define PetscErrorSetCatchable(a,b) 0
382: #define PetscExceptionCaught(a,b) PETSC_FALSE
383: #define PetscExceptionValue(a) PETSC_FALSE
384: #define PetscExceptionTry1(a,b) a
385: #endif
387: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void);
388: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **);
389: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
390: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
391: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
392: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
393: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
394: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
395: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
396: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
397: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void);
398: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*);
399: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
400: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void);
402: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
403: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSetFPTrap(PetscFPTrap);
405: /*
406: Allows the code to build a stack frame as it runs
407: */
408: #if defined(PETSC_USE_DEBUG)
410: #define PETSCSTACKSIZE 15
412: typedef struct {
413: const char *function[PETSCSTACKSIZE];
414: const char *file[PETSCSTACKSIZE];
415: const char *directory[PETSCSTACKSIZE];
416: int line[PETSCSTACKSIZE];
417: int currentsize;
418: } PetscStack;
421: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCopy(PetscStack*,PetscStack*);
422: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPrint(PetscStack*,FILE* fp);
424: #define PetscStackActive (petscstack != 0)
427: /*MC
429: used for error handling.
431: Synopsis:
434: Usage:
435: .vb
436: int something;
439: .ve
441: Notes:
442: Not available in Fortran
444: Level: developer
446: .seealso: PetscFunctionReturn()
448: .keywords: traceback, error handling
449: M*/
451: {\
452: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
453: petscstack->function[petscstack->currentsize] = __FUNCT__; \
454: petscstack->file[petscstack->currentsize] = __FILE__; \
455: petscstack->directory[petscstack->currentsize] = __SDIR__; \
456: petscstack->line[petscstack->currentsize] = __LINE__; \
457: petscstack->currentsize++; \
458: }}
460: #define PetscStackPush(n) \
461: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
462: petscstack->function[petscstack->currentsize] = n; \
463: petscstack->file[petscstack->currentsize] = "unknown"; \
464: petscstack->directory[petscstack->currentsize] = "unknown"; \
465: petscstack->line[petscstack->currentsize] = 0; \
466: petscstack->currentsize++; \
467: }}
469: #define PetscStackPop \
470: {if (petscstack && petscstack->currentsize > 0) { \
471: petscstack->currentsize--; \
472: petscstack->function[petscstack->currentsize] = 0; \
473: petscstack->file[petscstack->currentsize] = 0; \
474: petscstack->directory[petscstack->currentsize] = 0; \
475: petscstack->line[petscstack->currentsize] = 0; \
476: }};
478: /*MC
479: PetscFunctionReturn - Last executable line of each PETSc function
480: used for error handling. Replaces return()
482: Synopsis:
483: void return(0);
485: Usage:
486: .vb
487: ....
488: return(0);
489: }
490: .ve
492: Notes:
493: Not available in Fortran
495: Level: developer
499: .keywords: traceback, error handling
500: M*/
501: #define PetscFunctionReturn(a) \
502: {\
503: PetscStackPop; \
504: return(a);}
506: #define PetscFunctionReturnVoid() \
507: {\
508: PetscStackPop; \
509: return;}
512: #else
515: #define PetscFunctionReturn(a) return(a)
516: #define PetscFunctionReturnVoid() return
517: #define PetscStackPop
518: #define PetscStackPush(f)
519: #define PetscStackActive 0
521: #endif
523: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCreate(void);
524: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackView(PetscViewer);
525: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDestroy(void);
526: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPublish(void);
527: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDepublish(void);
531: #endif