Actual source code: petscerror.h
1: /* $Id: petscerror.h,v 1.59 2001/09/07 20:13:16 bsmith Exp $ */
2: /*
3: Contains all error handling code for PETSc.
4: */
7: #include petsc.h
8: PETSC_EXTERN_CXX_BEGIN
10: #if defined(PETSC_HAVE_AMS)
11: #include "ams.h"
12: #endif
14: /*
15: Defines the directory where the compiled source is located; used
16: in printing error messages. Each makefile has an entry
17: LOCDIR = thedirectory
18: and bmake/common_variables includes in CCPPFLAGS -D__SDIR__='"${LOCDIR}"'
19: which is a flag passed to the C/C++ compilers.
20: */
23: #endif
25: /*
26: Defines the function where the compiled source is located; used
27: in printing error messages.
28: */
31: #endif
33: /*
34: These are the generic error codes. These error codes are used
35: many different places in the PETSc source code.
37: */
38: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
39: #define PETSC_ERR_MEM_MALLOC_0 85 /* cannot malloc zero size */
40: #define PETSC_ERR_SUP 56 /* no support for requested operation */
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_MAX_ITER 82 /* Maximum iterations reached */
49: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
50: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
51: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
52: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
53: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
54: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
55: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
56: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
57: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
58: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
59: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
61: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
62: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
63: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
64: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
66: #define PETSC_ERR_KSP_BRKDWN 70 /* break down in a Krylov method */
68: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
69: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
71: #define PETSC_ERR_MESH_NULL_ELEM 84 /* Element had no interior */
73: #define PETSC_ERR_DISC_SING_JAC 83 /* Singular element Jacobian */
75: #if defined(PETSC_USE_DEBUG)
77: /*MC
78: SETERRQ - Macro that is called when an error has been detected,
80: Not Collective
82: Synopsis:
83: void SETERRQ(int errorcode,char *message)
86: Input Parameters:
87: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
88: - message - error message
90: Level: beginner
92: Notes:
93: Once the error handler is called the calling function is then returned from with the given error code.
95: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
98: Experienced users can set the error handler with PetscPushErrorHandler().
100: Concepts: error^setting condition
102: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
103: M*/
104: #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}
106: /*MC
107: SETERRQ1 - Macro that is called when an error has been detected,
109: Not Collective
111: Synopsis:
112: void SETERRQ1(int errorcode,char *formatmessage,arg)
115: Input Parameters:
116: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
117: . message - error message in the printf format
118: - arg - argument (for example an integer, string or double)
120: Level: beginner
122: Notes:
123: Once the error handler is called the calling function is then returned from with the given error code.
125: Experienced users can set the error handler with PetscPushErrorHandler().
127: Concepts: error^setting condition
129: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
130: M*/
131: #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}
133: /*MC
134: SETERRQ2 - Macro that is called when an error has been detected,
136: Not Collective
138: Synopsis:
139: void SETERRQ2(int errorcode,char *formatmessage,arg1,arg2)
142: Input Parameters:
143: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
144: . message - error message in the printf format
145: . arg1 - argument (for example an integer, string or double)
146: - arg2 - argument (for example an integer, string or double)
148: Level: beginner
150: Notes:
151: Once the error handler is called the calling function is then returned from with the given error code.
153: Experienced users can set the error handler with PetscPushErrorHandler().
155: Concepts: error^setting condition
157: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
158: M*/
159: #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}
161: /*MC
162: SETERRQ3 - Macro that is called when an error has been detected,
164: Not Collective
166: Synopsis:
167: void SETERRQ3(int errorcode,char *formatmessage,arg1,arg2,arg3)
170: Input Parameters:
171: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
172: . message - error message in the printf format
173: . arg1 - argument (for example an integer, string or double)
174: . arg2 - argument (for example an integer, string or double)
175: - arg3 - argument (for example an integer, string or double)
177: Level: beginner
179: Notes:
180: Once the error handler is called the calling function is then returned from with the given error code.
182: Experienced users can set the error handler with PetscPushErrorHandler().
184: Concepts: error^setting condition
186: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
187: M*/
188: #define SETERRQ3(n,s,a1,a2,a3) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);}
190: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
191: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
192: #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);}
193: #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);}
194: #define SETERRABORT(comm,n,s) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}
196: /*MC
197: CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
199: Not Collective
201: Synopsis:
202: void CHKERRQ(int errorcode)
205: Input Parameters:
206: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
208: Level: beginner
210: Notes:
211: Once the error handler is called the calling function is then returned from with the given error code.
213: Experienced users can set the error handler with PetscPushErrorHandler().
215: Concepts: error^setting condition
217: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
218: M*/
219: #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
221: #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
222: #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
224: /*MC
225: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
227: Not Collective
229: Synopsis:
230: CHKMEMQ;
232: Level: beginner
234: Notes:
235: Must run with the option -trdebug to enable this option
237: Once the error handler is called the calling function is then returned from with the given error code.
239: By defaults prints location where memory that is corrupted was allocated.
241: Concepts: memory corruption
243: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(),
244: PetscTrValid()
245: M*/
246: #define CHKMEMQ {int _7_PetscTrValid(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}
248: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
249: extern int __gierr;
250: #define _ __g
252: #endif
254: #else
255: #define SETERRQ(n,s) ;
256: #define SETERRQ1(n,s,a1) ;
257: #define SETERRQ2(n,s,a1,a2) ;
258: #define SETERRQ3(n,s,a1,a2,a3) ;
259: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
260: #define SETERRABORT(comm,n,s) ;
262: #define CHKERRQ(n) ;
263: #define CHKERRABORT(comm,n) ;
264: #define CHKERRCONTINUE(n) ;
266: #define CHKMEMQ ;
268: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
269: #define _
271: #endif
273: #endif
275: EXTERN int PetscErrorMessage(int,const char*[],char **);
276: EXTERN int PetscTraceBackErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
277: EXTERN int PetscIgnoreErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
278: EXTERN int PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
279: EXTERN int PetscStopErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
280: EXTERN int PetscAbortErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
281: EXTERN int PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
282: EXTERN int PetscError(int,const char*,const char*,const char*,int,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
283: EXTERN int PetscPushErrorHandler(int (*handler)(int,const char*,const char*,const char*,int,int,const char*,void*),void*);
284: EXTERN int PetscPopErrorHandler(void);
285: EXTERN int PetscDefaultSignalHandler(int,void*);
286: EXTERN int PetscPushSignalHandler(int (*)(int,void *),void*);
287: EXTERN int PetscPopSignalHandler(void);
289: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
290: EXTERN int PetscSetFPTrap(PetscFPTrap);
292: /*
293: Allows the code to build a stack frame as it runs
294: */
295: #if defined(PETSC_USE_STACK)
297: #define PETSCSTACKSIZE 15
299: typedef struct {
300: const char *function[PETSCSTACKSIZE];
301: const char *file[PETSCSTACKSIZE];
302: const char *directory[PETSCSTACKSIZE];
303: int line[PETSCSTACKSIZE];
304: int currentsize;
305: } PetscStack;
307: extern PetscStack *petscstack;
308: EXTERN int PetscStackCopy(PetscStack*,PetscStack*);
309: EXTERN int PetscStackPrint(PetscStack*,FILE* fp);
311: #define PetscStackActive (petscstack != 0)
313: #if !defined(PETSC_HAVE_AMS)
315: /*MC
317: used for error handling.
319: Synopsis:
322: Usage:
323: .vb
324: int something;
327: .ve
329: Notes:
330: Not available in Fortran
332: Level: developer
334: .seealso: PetscFunctionReturn()
336: .keywords: traceback, error handling
337: M*/
339: {\
340: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
341: petscstack->function[petscstack->currentsize] = __FUNCT__; \
342: petscstack->file[petscstack->currentsize] = __FILE__; \
343: petscstack->directory[petscstack->currentsize] = __SDIR__; \
344: petscstack->line[petscstack->currentsize] = __LINE__; \
345: petscstack->currentsize++; \
346: }}
348: #define PetscStackPush(n) \
349: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
350: petscstack->function[petscstack->currentsize] = n; \
351: petscstack->file[petscstack->currentsize] = "unknown"; \
352: petscstack->directory[petscstack->currentsize] = "unknown"; \
353: petscstack->line[petscstack->currentsize] = 0; \
354: petscstack->currentsize++; \
355: }}
357: #define PetscStackPop \
358: {if (petscstack && petscstack->currentsize > 0) { \
359: petscstack->currentsize--; \
360: petscstack->function[petscstack->currentsize] = 0; \
361: petscstack->file[petscstack->currentsize] = 0; \
362: petscstack->directory[petscstack->currentsize] = 0; \
363: petscstack->line[petscstack->currentsize] = 0; \
364: }};
366: /*MC
367: PetscFunctionReturn - Last executable line of each PETSc function
368: used for error handling. Replaces return()
370: Synopsis:
371: void return(0);
373: Usage:
374: .vb
375: ....
376: return(0);
377: }
378: .ve
380: Notes:
381: Not available in Fortran
383: Level: developer
387: .keywords: traceback, error handling
388: M*/
389: #define PetscFunctionReturn(a) \
390: {\
391: PetscStackPop; \
392: return(a);}
394: #define PetscFunctionReturnVoid() \
395: {\
396: PetscStackPop; \
397: return;}
399: #else
401: /*
402: Duplicate Code for when the ALICE Memory Snooper (AMS)
403: is being used. When PETSC_HAVE_AMS is defined.
405: stack_mem is the AMS memory that contains fields for the
406: number of stack frames and names of the stack frames
407: */
409: extern AMS_Memory stack_mem;
410: extern int stack_err;
413: {\
414: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
415: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
416: petscstack->function[petscstack->currentsize] = __FUNCT__; \
417: petscstack->file[petscstack->currentsize] = __FILE__; \
418: petscstack->directory[petscstack->currentsize] = __SDIR__; \
419: petscstack->line[petscstack->currentsize] = __LINE__; \
420: petscstack->currentsize++; \
421: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
422: }}
424: #define PetscStackPush(n) \
425: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
426: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
427: petscstack->function[petscstack->currentsize] = n; \
428: petscstack->file[petscstack->currentsize] = "unknown"; \
429: petscstack->directory[petscstack->currentsize] = "unknown"; \
430: petscstack->line[petscstack->currentsize] = 0; \
431: petscstack->currentsize++; \
432: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
433: }}
435: #define PetscStackPop \
436: {if (petscstack && petscstack->currentsize > 0) { \
437: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
438: petscstack->currentsize--; \
439: petscstack->function[petscstack->currentsize] = 0; \
440: petscstack->file[petscstack->currentsize] = 0; \
441: petscstack->directory[petscstack->currentsize] = 0; \
442: petscstack->line[petscstack->currentsize] = 0; \
443: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
444: }};
446: #define PetscFunctionReturn(a) \
447: {\
448: PetscStackPop; \
449: return(a);}
451: #define PetscFunctionReturnVoid() \
452: {\
453: PetscStackPop; \
454: return;}
457: #endif
459: #else
462: #define PetscFunctionReturn(a) return(a)
463: #define PetscFunctionReturnVoid() return()
464: #define PetscStackPop
465: #define PetscStackPush(f)
466: #define PetscStackActive 0
468: #endif
470: EXTERN int PetscStackCreate(void);
471: EXTERN int PetscStackView(PetscViewer);
472: EXTERN int PetscStackDestroy(void);
473: EXTERN int PetscStackPublish(void);
474: EXTERN int PetscStackDepublish(void);
477: PETSC_EXTERN_CXX_END
478: #endif