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
35: */
36: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
37: #define PETSC_ERR_MEM_MALLOC_0 85 /* cannot malloc zero size */
38: #define PETSC_ERR_SUP 56 /* no support for requested operation */
39: #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */
40: #define PETSC_ERR_ORDER 58 /* operation done in wrong order */
41: #define PETSC_ERR_SIG 59 /* signal received */
42: #define PETSC_ERR_FP 72 /* floating point exception */
43: #define PETSC_ERR_COR 74 /* corrupted PETSc object */
44: #define PETSC_ERR_LIB 76 /* error in library called by PETSc */
45: #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */
46: #define PETSC_ERR_MEMC 78 /* memory corruption */
47: #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */
48: #define PETSC_ERR_USER 83 /* user has not provided needed function */
50: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
51: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
52: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
53: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
54: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
55: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
56: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
57: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
58: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
59: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
60: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
61: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */
62: #define PETSC_ERR_ARG_DOMAIN 87 /* argument is not in domain of function */
64: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
65: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
66: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
67: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
69: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
70: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
72: #if defined(PETSC_USE_ERRORCHECKING)
74: /*MC
75: SETERRQ - Macro that is called when an error has been detected,
77: Not Collective
79: Synopsis:
80: void SETERRQ(PetscErrorCode errorcode,char *message)
83: Input Parameters:
84: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
85: - message - error message
87: Level: beginner
89: Notes:
90: Once the error handler is called the calling function is then returned from with the given error code.
92: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
95: Experienced users can set the error handler with PetscPushErrorHandler().
97: Concepts: error^setting condition
99: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
100: M*/
101: #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}
103: /*MC
104: SETERRQ1 - Macro that is called when an error has been detected,
106: Not Collective
108: Synopsis:
109: void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)
112: Input Parameters:
113: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
114: . message - error message in the printf format
115: - arg - argument (for example an integer, string or double)
117: Level: beginner
119: Notes:
120: Once the error handler is called the calling function is then returned from with the given error code.
122: Experienced users can set the error handler with PetscPushErrorHandler().
124: Concepts: error^setting condition
126: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
127: M*/
128: #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}
130: /*MC
131: SETERRQ2 - Macro that is called when an error has been detected,
133: Not Collective
135: Synopsis:
136: void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)
139: Input Parameters:
140: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
141: . message - error message in the printf format
142: . arg1 - argument (for example an integer, string or double)
143: - arg2 - argument (for example an integer, string or double)
145: Level: beginner
147: Notes:
148: Once the error handler is called the calling function is then returned from with the given error code.
150: Experienced users can set the error handler with PetscPushErrorHandler().
152: Concepts: error^setting condition
154: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
155: M*/
156: #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}
158: /*MC
159: SETERRQ3 - Macro that is called when an error has been detected,
161: Not Collective
163: Synopsis:
164: void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)
167: Input Parameters:
168: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
169: . message - error message in the printf format
170: . arg1 - argument (for example an integer, string or double)
171: . arg2 - argument (for example an integer, string or double)
172: - arg3 - argument (for example an integer, string or double)
174: Level: beginner
176: Notes:
177: Once the error handler is called the calling function is then returned from with the given error code.
179: There are also versions for 4, 5, 6 and 7 arguments.
181: Experienced users can set the error handler with PetscPushErrorHandler().
183: Concepts: error^setting condition
185: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
186: M*/
187: #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);}
189: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
190: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
191: #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);}
192: #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);}
193: #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}
195: /*MC
196: CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
198: Not Collective
200: Synopsis:
201: void CHKERRQ(PetscErrorCode errorcode)
204: Input Parameters:
205: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
207: Level: beginner
209: Notes:
210: Once the error handler is called the calling function is then returned from with the given error code.
212: Experienced users can set the error handler with PetscPushErrorHandler().
214: CHKERRQ(n) is fundamentally a macro replacement for
215: if (n) return(PetscError(...,n,...));
217: Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
218: highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
219: it cannot be used in functions which return(void) or any other datatype. In these types of functions,
220: a more appropriate construct for using PETSc Error Handling would be
221: if (n) {PetscError(....); return(YourReturnType);}
223: Concepts: error^setting condition
225: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
226: M*/
227: #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
229: #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
230: #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
232: /*MC
233: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
235: Not Collective
237: Synopsis:
238: CHKMEMQ;
240: Level: beginner
242: Notes:
243: Must run with the option -malloc_debug to enable this option
245: Once the error handler is called the calling function is then returned from with the given error code.
247: By defaults prints location where memory that is corrupted was allocated.
249: Use CHKMEMA for functions that return void
251: Concepts: memory corruption
253: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
254: PetscMallocValidate()
255: M*/
256: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}
258: #define CHKMEMA {PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);}
260: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
262: #define _ __g
264: #endif
266: #define PETSC_EXCEPTIONS_MAX 256
272: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode);
273: EXTERN void PETSC_DLLEXPORT PetscExceptionPop(PetscErrorCode);
275: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorSetCatchable(PetscErrorCode,PetscTruth);
277: /*MC
278: PetscExceptionCaught - Indicates if exception zierr was caught.
280: Not Collective
282: Synopsis:
283: PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);
285: Input Parameters:
286: + xierr - error code returned from PetscExceptionTry1()
287: - zierr - error code you want it to be
289: Level: advanced
291: Notes:
292: PETSc must not be configured using the option --with-errorchecking=0 for this to work
294: Concepts: exceptions, exception hanlding
296: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
297: CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
298: M*/
299: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
300: PetscInt i;
301: if (xierr != zierr) return PETSC_FALSE;
302: for (i=0; i<PetscErrorUncatchableCount; i++) {
303: if (PetscErrorUncatchable[i] == zierr) {
304: return PETSC_FALSE;
305: }
306: }
307: return PETSC_TRUE;
308: }
310: /*MC
311: PetscExceptionValue - Indicates if the error code is one that is currently being tried
313: Not Collective
315: Synopsis:
316: PetscTruth PetscExceptionValue(PetscErrorCode xierr);
318: Input Parameters:
319: . xierr - error code
321: Level: developer
323: Notes:
324: PETSc must not be configured using the option --with-errorchecking=0 for this to work
326: Concepts: exceptions, exception hanlding
328: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
329: CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
330: M*/
331: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) {
332: PetscInt i;
333: for (i=0; i<PetscExceptionsCount; i++) {
334: if (PetscExceptions[i] == zierr) {
335: return PETSC_TRUE;
336: }
337: }
338: return PETSC_FALSE;
339: }
341: /*MC
342: PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception,
343: rather than an error. That is if that error code is treated the program returns to this level,
344: but does not call the error handlers
346: Not Collective
348: Synopsis:
349: PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);
351: Level: advanced
353: Notes:
354: PETSc must not be configured using the option --with-errorchecking=0 for this to work
356: Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in
357: PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example
358: of how the local try is ignored if a higher (in the stack) one is also in effect.
360: Concepts: exceptions, exception hanlding
362: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
363: CHKERRQ(), PetscExceptionCaught()
364: M*/
366: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)
368: #else
370: /*
371: These are defined to be empty for when error checking is turned off, with config/configure.py --with-errorchecking=0
372: */
374: #define SETERRQ(n,s) ;
375: #define SETERRQ1(n,s,a1) ;
376: #define SETERRQ2(n,s,a1,a2) ;
377: #define SETERRQ3(n,s,a1,a2,a3) ;
378: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
379: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
380: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
381: #define SETERRABORT(comm,n,s) ;
383: #define CHKERRQ(n) ;
384: #define CHKERRABORT(comm,n) ;
385: #define CHKERRCONTINUE(n) ;
387: #define CHKMEMQ ;
389: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
390: #define _
392: #endif
394: #define PetscErrorSetCatchable(a,b) 0
395: #define PetscExceptionCaught(a,b) PETSC_FALSE
396: #define PetscExceptionValue(a) PETSC_FALSE
397: #define PetscExceptionTry1(a,b) a
398: #endif
400: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void);
401: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **);
402: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
403: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
404: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
405: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
406: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
407: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
408: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscReturnErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
409: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
410: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
411: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void);
412: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*);
413: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
414: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void);
416: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
417: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSetFPTrap(PetscFPTrap);
419: /*
420: Allows the code to build a stack frame as it runs
421: */
422: #if defined(PETSC_USE_DEBUG)
424: #define PETSCSTACKSIZE 15
426: typedef struct {
427: const char *function[PETSCSTACKSIZE];
428: const char *file[PETSCSTACKSIZE];
429: const char *directory[PETSCSTACKSIZE];
430: int line[PETSCSTACKSIZE];
431: int currentsize;
432: } PetscStack;
435: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCopy(PetscStack*,PetscStack*);
436: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPrint(PetscStack*,FILE* fp);
438: #define PetscStackActive (petscstack != 0)
441: /*MC
443: used for error handling.
445: Synopsis:
448: Usage:
449: .vb
450: int something;
453: .ve
455: Notes:
456: Not available in Fortran
458: Level: developer
460: .seealso: PetscFunctionReturn()
462: .keywords: traceback, error handling
463: M*/
465: {\
466: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
467: petscstack->function[petscstack->currentsize] = __FUNCT__; \
468: petscstack->file[petscstack->currentsize] = __FILE__; \
469: petscstack->directory[petscstack->currentsize] = __SDIR__; \
470: petscstack->line[petscstack->currentsize] = __LINE__; \
471: petscstack->currentsize++; \
472: }}
474: #define PetscStackPush(n) \
475: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
476: petscstack->function[petscstack->currentsize] = n; \
477: petscstack->file[petscstack->currentsize] = "unknown"; \
478: petscstack->directory[petscstack->currentsize] = "unknown"; \
479: petscstack->line[petscstack->currentsize] = 0; \
480: petscstack->currentsize++; \
481: }}
483: #define PetscStackPop \
484: {if (petscstack && petscstack->currentsize > 0) { \
485: petscstack->currentsize--; \
486: petscstack->function[petscstack->currentsize] = 0; \
487: petscstack->file[petscstack->currentsize] = 0; \
488: petscstack->directory[petscstack->currentsize] = 0; \
489: petscstack->line[petscstack->currentsize] = 0; \
490: }};
492: /*MC
493: PetscFunctionReturn - Last executable line of each PETSc function
494: used for error handling. Replaces return()
496: Synopsis:
497: void return(0);
499: Usage:
500: .vb
501: ....
502: return(0);
503: }
504: .ve
506: Notes:
507: Not available in Fortran
509: Level: developer
513: .keywords: traceback, error handling
514: M*/
515: #define PetscFunctionReturn(a) \
516: {\
517: PetscStackPop; \
518: return(a);}
520: #define PetscFunctionReturnVoid() \
521: {\
522: PetscStackPop; \
523: return;}
526: #else
529: #define PetscFunctionReturn(a) return(a)
530: #define PetscFunctionReturnVoid() return
531: #define PetscStackPop
532: #define PetscStackPush(f)
533: #define PetscStackActive 0
535: #endif
537: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackCreate(void);
538: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackView(PetscViewer);
539: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDestroy(void);
540: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackPublish(void);
541: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStackDepublish(void);
545: #endif