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: */
8: #include petsc.h
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 */
60: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
61: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
62: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
63: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
65: #define PETSC_ERR_KSP_BRKDWN 70 /* break down in a Krylov method */
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: #define PETSC_ERR_MESH_NULL_ELEM 84 /* Element had no interior */
72: #define PETSC_ERR_DISC_SING_JAC 83 /* Singular element Jacobian */
74: #if defined(PETSC_USE_DEBUG)
76: /*MC
77: SETERRQ - Macro that is called when an error has been detected,
79: Not Collective
81: Synopsis:
82: void SETERRQ(int errorcode,char *message)
85: Input Parameters:
86: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
87: - message - error message
89: Level: beginner
91: Notes:
92: Once the error handler is called the calling function is then returned from with the given error code.
94: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
97: Experienced users can set the error handler with PetscPushErrorHandler().
99: Concepts: error^setting condition
101: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ(), SETERRQ1(), SETERRQ2(), SETERRQ3()
102: M*/
103: #define SETERRQ(n,s) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}
105: /*MC
106: SETERRQ1 - Macro that is called when an error has been detected,
108: Not Collective
110: Synopsis:
111: void SETERRQ1(int errorcode,char *formatmessage,arg)
114: Input Parameters:
115: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
116: . message - error message in the printf format
117: - arg - argument (for example an integer, string or double)
119: Level: beginner
121: Notes:
122: Once the error handler is called the calling function is then returned from with the given error code.
124: Experienced users can set the error handler with PetscPushErrorHandler().
126: Concepts: error^setting condition
128: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ(), SETERRQ(), SETERRQ2(), SETERRQ3()
129: M*/
130: #define SETERRQ1(n,s,a1) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}
132: /*MC
133: SETERRQ2 - Macro that is called when an error has been detected,
135: Not Collective
137: Synopsis:
138: void SETERRQ2(int errorcode,char *formatmessage,arg1,arg2)
141: Input Parameters:
142: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
143: . message - error message in the printf format
144: . arg1 - argument (for example an integer, string or double)
145: - arg2 - argument (for example an integer, string or double)
147: Level: beginner
149: Notes:
150: Once the error handler is called the calling function is then returned from with the given error code.
152: Experienced users can set the error handler with PetscPushErrorHandler().
154: Concepts: error^setting condition
156: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ(), SETERRQ1(), SETERRQ2(), SETERRQ3()
157: M*/
158: #define SETERRQ2(n,s,a1,a2) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}
160: /*MC
161: SETERRQ3 - Macro that is called when an error has been detected,
163: Not Collective
165: Synopsis:
166: void SETERRQ3(int errorcode,char *formatmessage,arg1,arg2,arg3)
169: Input Parameters:
170: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
171: . message - error message in the printf format
172: . arg1 - argument (for example an integer, string or double)
173: . arg2 - argument (for example an integer, string or double)
174: - arg3 - argument (for example an integer, string or double)
176: Level: beginner
178: Notes:
179: Once the error handler is called the calling function is then returned from with the given error code.
181: Experienced users can set the error handler with PetscPushErrorHandler().
183: Concepts: error^setting condition
185: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ(), SETERRQ1(), SETERRQ2(), 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(int 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: Concepts: error^setting condition
216: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ(), SETERRQ1(), SETERRQ2(), SETERRQ2()
217: M*/
218: #define CHKERRQ(n) if (n) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
220: #define CHKERRABORT(comm,n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
221: #define CHKERRCONTINUE(n) if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}
223: /*MC
224: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
226: Not Collective
228: Synopsis:
229: void CHKMEMQ(void)
231: Level: beginner
233: Notes:
234: Must run with the option -trdebug to enable this option
236: Once the error handler is called the calling function is then returned from with the given error code.
238: By defaults prints location where memory that is corrupted was allocated.
240: Concepts: memory corruption
242: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ(), SETERRQ1(), SETERRQ2(), SETERRQ2(),
243: PetscTrValid()
244: M*/
245: #define CHKMEMQ {int _7_PetscTrValid(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}
247: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
248: extern int __gierr;
249: #define _ __g
251: #endif
253: #else
254: #define SETERRQ(n,s) ;
255: #define SETERRQ1(n,s,a1) ;
256: #define SETERRQ2(n,s,a1,a2) ;
257: #define SETERRQ3(n,s,a1,a2,a3) ;
258: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
259: #define SETERRABORT(comm,n,s) ;
261: #define CHKERRQ(n) ;
262: #define CHKERRABORT(comm,n) ;
263: #define CHKERRCONTINUE(n) ;
265: #define CHKMEMQ ;
267: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
268: #define _
270: #endif
272: #endif
274: EXTERN int PetscErrorMessage(int,char**,char **);
275: EXTERN int PetscTraceBackErrorHandler(int,char*,char*,char*,int,int,char*,void*);
276: EXTERN int PetscIgnoreErrorHandler(int,char*,char*,char*,int,int,char*,void*);
277: EXTERN int PetscEmacsClientErrorHandler(int,char*,char*,char*,int,int,char*,void*);
278: EXTERN int PetscStopErrorHandler(int,char*,char*,char*,int,int,char*,void*);
279: EXTERN int PetscAbortErrorHandler(int,char*,char*,char*,int,int,char*,void*);
280: EXTERN int PetscAttachDebuggerErrorHandler(int,char*,char*,char*,int,int,char*,void*);
281: EXTERN int PetscError(int,char*,char*,char*,int,int,char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
282: EXTERN int PetscPushErrorHandler(int (*handler)(int,char*,char*,char*,int,int,char*,void*),void*);
283: EXTERN int PetscPopErrorHandler(void);
284: EXTERN int PetscDefaultSignalHandler(int,void*);
285: EXTERN int PetscPushSignalHandler(int (*)(int,void *),void*);
286: EXTERN int PetscPopSignalHandler(void);
288: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
289: EXTERN int PetscSetFPTrap(PetscFPTrap);
291: /*
292: Allows the code to build a stack frame as it runs
293: */
294: #if defined(PETSC_USE_STACK)
296: #define PETSCSTACKSIZE 15
298: typedef struct {
299: char *function[PETSCSTACKSIZE];
300: char *file[PETSCSTACKSIZE];
301: char *directory[PETSCSTACKSIZE];
302: int line[PETSCSTACKSIZE];
303: int currentsize;
304: } PetscStack;
306: extern PetscStack *petscstack;
307: EXTERN int PetscStackCopy(PetscStack*,PetscStack*);
308: EXTERN int PetscStackPrint(PetscStack*,FILE* fp);
310: #define PetscStackActive (petscstack != 0)
312: #if !defined(PETSC_HAVE_AMS)
314: /*MC
316: used for error handling.
318: Synopsis:
321: Usage:
322: .vb
323: int something;
326: .ve
328: Notes:
329: Not available in Fortran
331: Level: developer
333: .seealso: PetscFunctionReturn()
335: .keywords: traceback, error handling
336: M*/
338: {\
339: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
340: petscstack->function[petscstack->currentsize] = __FUNCT__; \
341: petscstack->file[petscstack->currentsize] = __FILE__; \
342: petscstack->directory[petscstack->currentsize] = __SDIR__; \
343: petscstack->line[petscstack->currentsize] = __LINE__; \
344: petscstack->currentsize++; \
345: }}
347: #define PetscStackPush(n) \
348: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
349: petscstack->function[petscstack->currentsize] = n; \
350: petscstack->file[petscstack->currentsize] = "unknown"; \
351: petscstack->directory[petscstack->currentsize] = "unknown"; \
352: petscstack->line[petscstack->currentsize] = 0; \
353: petscstack->currentsize++; \
354: }}
356: #define PetscStackPop \
357: {if (petscstack && petscstack->currentsize > 0) { \
358: petscstack->currentsize--; \
359: petscstack->function[petscstack->currentsize] = 0; \
360: petscstack->file[petscstack->currentsize] = 0; \
361: petscstack->directory[petscstack->currentsize] = 0; \
362: petscstack->line[petscstack->currentsize] = 0; \
363: }};
365: /*MC
366: PetscFunctionReturn - Last executable line of each PETSc function
367: used for error handling. Replaces return()
369: Synopsis:
370: void return(0);
372: Usage:
373: .vb
374: ....
375: return(0);
376: }
377: .ve
379: Notes:
380: Not available in Fortran
382: Level: developer
386: .keywords: traceback, error handling
387: M*/
388: #define PetscFunctionReturn(a) \
389: {\
390: PetscStackPop; \
391: return(a);}
393: #define PetscFunctionReturnVoid() \
394: {\
395: PetscStackPop; \
396: return;}
398: #else
400: /*
401: Duplicate Code for when the ALICE Memory Snooper (AMS)
402: is being used. When PETSC_HAVE_AMS is defined.
404: stack_mem is the AMS memory that contains fields for the
405: number of stack frames and names of the stack frames
406: */
408: extern AMS_Memory stack_mem;
409: extern int stack_err;
412: {\
413: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
414: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
415: petscstack->function[petscstack->currentsize] = __FUNCT__; \
416: petscstack->file[petscstack->currentsize] = __FILE__; \
417: petscstack->directory[petscstack->currentsize] = __SDIR__; \
418: petscstack->line[petscstack->currentsize] = __LINE__; \
419: petscstack->currentsize++; \
420: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
421: }}
423: #define PetscStackPush(n) \
424: {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
425: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
426: petscstack->function[petscstack->currentsize] = n; \
427: petscstack->file[petscstack->currentsize] = "unknown"; \
428: petscstack->directory[petscstack->currentsize] = "unknown"; \
429: petscstack->line[petscstack->currentsize] = 0; \
430: petscstack->currentsize++; \
431: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
432: }}
434: #define PetscStackPop \
435: {if (petscstack && petscstack->currentsize > 0) { \
436: if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
437: petscstack->currentsize--; \
438: petscstack->function[petscstack->currentsize] = 0; \
439: petscstack->file[petscstack->currentsize] = 0; \
440: petscstack->directory[petscstack->currentsize] = 0; \
441: petscstack->line[petscstack->currentsize] = 0; \
442: if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
443: }};
445: #define PetscFunctionReturn(a) \
446: {\
447: PetscStackPop; \
448: return(a);}
450: #define PetscFunctionReturnVoid() \
451: {\
452: PetscStackPop; \
453: return;}
456: #endif
458: #else
461: #define PetscFunctionReturn(a) return(a)
462: #define PetscFunctionReturnVoid() return()
463: #define PetscStackPop
464: #define PetscStackPush(f)
465: #define PetscStackActive 0
467: #endif
469: EXTERN int PetscStackCreate(void);
470: EXTERN int PetscStackView(PetscViewer);
471: EXTERN int PetscStackDestroy(void);
472: EXTERN int PetscStackPublish(void);
473: EXTERN int PetscStackDepublish(void);
476: #endif