Actual source code: petscerror.h
1: /*
2: Contains all error handling interfaces for PETSc.
3: */
7: #if defined(PETSC_HAVE_STRING_H)
8: #include <string.h> /* for strcmp */
9: #endif
13: /*
14: Defines the directory where the compiled source is located; used
15: in printing error messages. Each makefile has an entry
16: LOCDIR = thedirectory
17: and bmake/common_variables includes in CCPPFLAGS -D__SDIR__=${LOCDIR}
18: which is a flag passed to the C/C++ compilers. This declaration below
19: is only needed if some code is compiled without the -D__SDIR__
20: */
23: #endif
25: /*
26: Defines the function where the compiled source is located; used
27: in printing error messages. This is defined here in case the user
28: does not declare it.
29: */
32: #endif
34: /*
35: These are the generic error codes. These error codes are used
36: many different places in the PETSc source code. The string versions are
37: at src/sys/error/err.c any changes here must also be made there
38: These are also define in include/finclude/petscerror.h any CHANGES here
39: must be also made there.
41: */
42: #define PETSC_ERR_MIN_VALUE 54 /* should always be one less then the smallest value */
44: #define PETSC_ERR_MEM 55 /* unable to allocate requested memory */
45: #define PETSC_ERR_SUP 56 /* no support for requested operation */
46: #define PETSC_ERR_SUP_SYS 57 /* no support for requested operation on this computer system */
47: #define PETSC_ERR_ORDER 58 /* operation done in wrong order */
48: #define PETSC_ERR_SIG 59 /* signal received */
49: #define PETSC_ERR_FP 72 /* floating point exception */
50: #define PETSC_ERR_COR 74 /* corrupted PETSc object */
51: #define PETSC_ERR_LIB 76 /* error in library called by PETSc */
52: #define PETSC_ERR_PLIB 77 /* PETSc library generated inconsistent data */
53: #define PETSC_ERR_MEMC 78 /* memory corruption */
54: #define PETSC_ERR_CONV_FAILED 82 /* iterative method (KSP or SNES) failed */
55: #define PETSC_ERR_USER 83 /* user has not provided needed function */
56: #define PETSC_ERR_SYS 88 /* error in system call */
58: #define PETSC_ERR_ARG_SIZ 60 /* nonconforming object sizes used in operation */
59: #define PETSC_ERR_ARG_IDN 61 /* two arguments not allowed to be the same */
60: #define PETSC_ERR_ARG_WRONG 62 /* wrong argument (but object probably ok) */
61: #define PETSC_ERR_ARG_CORRUPT 64 /* null or corrupted PETSc object as argument */
62: #define PETSC_ERR_ARG_OUTOFRANGE 63 /* input argument, out of range */
63: #define PETSC_ERR_ARG_BADPTR 68 /* invalid pointer argument */
64: #define PETSC_ERR_ARG_NOTSAMETYPE 69 /* two args must be same object type */
65: #define PETSC_ERR_ARG_NOTSAMECOMM 80 /* two args must be same communicators */
66: #define PETSC_ERR_ARG_WRONGSTATE 73 /* object in argument is in wrong state, e.g. unassembled mat */
67: #define PETSC_ERR_ARG_TYPENOTSET 89 /* the type of the object has not yet been set */
68: #define PETSC_ERR_ARG_INCOMP 75 /* two arguments are incompatible */
69: #define PETSC_ERR_ARG_NULL 85 /* argument is null that should not be */
70: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86 /* type name doesn't match any registered type */
72: #define PETSC_ERR_FILE_OPEN 65 /* unable to open file */
73: #define PETSC_ERR_FILE_READ 66 /* unable to read from file */
74: #define PETSC_ERR_FILE_WRITE 67 /* unable to write to file */
75: #define PETSC_ERR_FILE_UNEXPECTED 79 /* unexpected data in file */
77: #define PETSC_ERR_MAT_LU_ZRPVT 71 /* detected a zero pivot during LU factorization */
78: #define PETSC_ERR_MAT_CH_ZRPVT 81 /* detected a zero pivot during Cholesky factorization */
80: #define PETSC_ERR_FLOP_COUNT 90
81: #define PETSC_ERR_NOT_CONVERGED 91 /* solver did not converge */
82: #define PETSC_ERR_MAX_VALUE 92 /* this is always the one more than the largest error code */
84: #define PetscStringizeArg(a) #a
85: #define PetscStringize(a) PetscStringizeArg(a)
88: #if defined(PETSC_USE_ERRORCHECKING)
90: /*MC
91: SETERRQ - Macro that is called when an error has been detected,
93: Synopsis:
94: PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode errorcode,char *message)
96: Not Collective
98: Input Parameters:
99: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
100: - message - error message
102: Level: beginner
104: Notes:
105: Once the error handler is called the calling function is then returned from with the given error code.
107: See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
109: In Fortran MPI_Abort() is always called
111: Experienced users can set the error handler with PetscPushErrorHandler().
113: Concepts: error^setting condition
115: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
116: M*/
117: #define SETERRQ(comm,n,s) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s)
119: /*MC
120: SETERRQ1 - Macro that is called when an error has been detected,
122: Synopsis:
123: PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg)
125: Not Collective
127: Input Parameters:
128: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
129: . message - error message in the printf format
130: - arg - argument (for example an integer, string or double)
132: Level: beginner
134: Notes:
135: Once the error handler is called the calling function is then returned from with the given error code.
137: Experienced users can set the error handler with PetscPushErrorHandler().
139: Concepts: error^setting condition
141: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
142: M*/
143: #define SETERRQ1(comm,n,s,a1) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1)
145: /*MC
146: SETERRQ2 - Macro that is called when an error has been detected,
148: Synopsis:
149: PetscErrorCode SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)
151: Not Collective
153: Input Parameters:
154: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
155: . message - error message in the printf format
156: . arg1 - argument (for example an integer, string or double)
157: - arg2 - argument (for example an integer, string or double)
159: Level: beginner
161: Notes:
162: Once the error handler is called the calling function is then returned from with the given error code.
164: Experienced users can set the error handler with PetscPushErrorHandler().
166: Concepts: error^setting condition
168: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
169: M*/
170: #define SETERRQ2(comm,n,s,a1,a2) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2)
172: /*MC
173: SETERRQ3 - Macro that is called when an error has been detected,
175: Synopsis:
176: PetscErrorCode SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)
178: Not Collective
180: Input Parameters:
181: + errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
182: . message - error message in the printf format
183: . arg1 - argument (for example an integer, string or double)
184: . arg2 - argument (for example an integer, string or double)
185: - arg3 - argument (for example an integer, string or double)
187: Level: beginner
189: Notes:
190: Once the error handler is called the calling function is then returned from with the given error code.
192: There are also versions for 4, 5, 6 and 7 arguments.
194: Experienced users can set the error handler with PetscPushErrorHandler().
196: Concepts: error^setting condition
198: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
199: M*/
200: #define SETERRQ3(comm,n,s,a1,a2,a3) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3)
202: #define SETERRQ4(comm,n,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)
203: #define SETERRQ5(comm,n,s,a1,a2,a3,a4,a5) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)
204: #define SETERRQ6(comm,n,s,a1,a2,a3,a4,a5,a6) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)
205: #define SETERRQ7(comm,n,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)
206: #define SETERRABORT(comm,n,s) do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,n);} while (0)
208: /*MC
209: CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
211: Synopsis:
212: PetscErrorCode CHKERRQ(PetscErrorCode errorcode)
214: Not Collective
216: Input Parameters:
217: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
219: Level: beginner
221: Notes:
222: Once the error handler is called the calling function is then returned from with the given error code.
224: Experienced users can set the error handler with PetscPushErrorHandler().
226: CHKERRQ(n) is fundamentally a macro replacement for
227: if (n) return(PetscError(...,n,...));
229: Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
230: highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
231: it cannot be used in functions which return(void) or any other datatype. In these types of functions,
232: you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
233: if (n) {PetscError(....); return(YourReturnType);}
234: where you may pass back a PETSC_NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
235: MPI_Abort() returned immediately.
237: In Fortran MPI_Abort() is always called
239: Concepts: error^setting condition
241: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
242: M*/
243: #define CHKERRQ(n) do {if (PetscUnlikely(n)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");} while (0)
245: #define CHKERRV(n) do {if (PetscUnlikely(n)) {n = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");return;}} while(0)
246: #define CHKERRABORT(comm,n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,n);}} while (0)
247: #define CHKERRCONTINUE(n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");}} while (0)
249: #ifdef PETSC_CLANGUAGE_CXX
251: /*MC
252: CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception
254: Synopsis:
255: void CHKERRXX(PetscErrorCode errorcode)
257: Not Collective
259: Input Parameters:
260: . errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
262: Level: beginner
264: Notes:
265: Once the error handler throws a ??? exception.
267: You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
268: or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.
270: Concepts: error^setting condition
272: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
273: M*/
274: #define CHKERRXX(n) do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_IN_CXX,0);}} while(0)
276: #endif
278: /*MC
279: CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
281: Synopsis:
282: CHKMEMQ;
284: Not Collective
286: Level: beginner
288: Notes:
289: Must run with the option -malloc_debug to enable this option
291: Once the error handler is called the calling function is then returned from with the given error code.
293: By defaults prints location where memory that is corrupted was allocated.
295: Use CHKMEMA for functions that return void
297: Concepts: memory corruption
299: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
300: PetscMallocValidate()
301: M*/
302: #define CHKMEMQ do {PetscErrorCode _7_PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} while(0)
304: #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__)
306: #if defined(PETSC_UNDERSCORE_CHKERR)
308: #define _ __g
310: #endif
312: #else /* PETSC_USE_ERRORCHECKING */
314: /*
315: These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0
316: */
318: #define SETERRQ(c,n,s)
319: #define SETERRQ1(c,n,s,a1)
320: #define SETERRQ2(c,n,s,a1,a2)
321: #define SETERRQ3(c,n,s,a1,a2,a3)
322: #define SETERRQ4(c,n,s,a1,a2,a3,a4)
323: #define SETERRQ5(c,n,s,a1,a2,a3,a4,a5)
324: #define SETERRQ6(c,n,s,a1,a2,a3,a4,a5,a6)
325: #define SETERRABORT(comm,n,s)
327: #define CHKERRQ(n) ;
328: #define CHKERRABORT(comm,n) ;
329: #define CHKERRCONTINUE(n) ;
330: #define CHKMEMQ ;
332: #ifdef PETSC_CLANGUAGE_CXX
333: #define CHKERRXX(n) ;
334: #endif
336: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
337: #define _
339: #endif
341: #endif /* PETSC_USE_ERRORCHECKING */
343: /*E
344: PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers
346: Level: advanced
348: PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated
350: Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandling()
352: .seealso: PetscError(), SETERRXX()
353: E*/
354: typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;
360: #include <sstream>
362: #endif
376: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
379: /*
380: Allows the code to build a stack frame as it runs
381: */
382: #if defined(PETSC_USE_DEBUG) && !defined(PETSC_USE_PTHREAD)
384: #define PETSCSTACKSIZE 64
386: typedef struct {
387: const char *function[PETSCSTACKSIZE];
388: const char *file[PETSCSTACKSIZE];
389: const char *directory[PETSCSTACKSIZE];
390: int line[PETSCSTACKSIZE];
391: int currentsize;
392: } PetscStack;
398: #define PetscStackActive (petscstack != 0)
400: /*MC
402: used for error handling.
404: Synopsis:
407: Not Collective
409: Usage:
410: .vb
411: int something;
414: .ve
416: Notes:
417: Not available in Fortran
419: Level: developer
421: .seealso: PetscFunctionReturn()
423: .keywords: traceback, error handling
424: M*/
426: do { \
427: if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
428: petscstack->function[petscstack->currentsize] = PETSC_FUNCTION_NAME; \
429: petscstack->file[petscstack->currentsize] = __FILE__; \
430: petscstack->directory[petscstack->currentsize] = __SDIR__; \
431: petscstack->line[petscstack->currentsize] = __LINE__; \
432: petscstack->currentsize++; \
433: } \
435: } while (0)
438: if (strcmp(PETSC_FUNCTION_NAME,__FUNCT__) && strcmp(__FUNCT__,"User provided function")) { \
439: (*PetscErrorPrintf)("%s%s:%d: __FUNCT__=\"%s\" does not agree with %s=\"%s\"\n",__SDIR__,__FILE__,__LINE__,__FUNCT__,PetscStringize(PETSC_FUNCTION_NAME),PETSC_FUNCTION_NAME); \
440: } \
441: } while (0)
443: #define PetscStackPush(n) \
444: do {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) { \
445: petscstack->function[petscstack->currentsize] = n; \
446: petscstack->file[petscstack->currentsize] = "unknown"; \
447: petscstack->directory[petscstack->currentsize] = "unknown"; \
448: petscstack->line[petscstack->currentsize] = 0; \
449: petscstack->currentsize++; \
450: } CHKMEMQ;} while (0)
452: #define PetscStackPop \
453: do {CHKMEMQ; if (petscstack && petscstack->currentsize > 0) { \
454: petscstack->currentsize--; \
455: petscstack->function[petscstack->currentsize] = 0; \
456: petscstack->file[petscstack->currentsize] = 0; \
457: petscstack->directory[petscstack->currentsize] = 0; \
458: petscstack->line[petscstack->currentsize] = 0; \
459: }} while (0)
461: /*MC
462: PetscFunctionReturn - Last executable line of each PETSc function
463: used for error handling. Replaces return()
465: Synopsis:
466: void return(0);
468: Not Collective
470: Usage:
471: .vb
472: ....
473: return(0);
474: }
475: .ve
477: Notes:
478: Not available in Fortran
480: Level: developer
484: .keywords: traceback, error handling
485: M*/
486: #define PetscFunctionReturn(a) \
487: do {\
488: if (petscstack && petscstack->currentsize > 0) { \
489: petscstack->currentsize--; \
490: petscstack->function[petscstack->currentsize] = 0; \
491: petscstack->file[petscstack->currentsize] = 0; \
492: petscstack->directory[petscstack->currentsize] = 0; \
493: petscstack->line[petscstack->currentsize] = 0; \
494: }\
495: return(a);} while (0)
497: #define PetscFunctionReturnVoid() \
498: do {\
499: if (petscstack && petscstack->currentsize > 0) { \
500: petscstack->currentsize--; \
501: petscstack->function[petscstack->currentsize] = 0; \
502: petscstack->file[petscstack->currentsize] = 0; \
503: petscstack->directory[petscstack->currentsize] = 0; \
504: petscstack->line[petscstack->currentsize] = 0; \
505: }\
506: return;} while (0)
508: #else
511: #define PetscFunctionReturn(a) return(a)
512: #define PetscFunctionReturnVoid() return
513: #define PetscStackPop CHKMEMQ
514: #define PetscStackPush(f) CHKMEMQ
515: #define PetscStackActive 0
517: #endif
519: /*
520: PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.
522: Input Parameters:
523: + name - string that gives the name of the function being called
524: - routine - actual call to the routine
526: Developer Note: this is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.
528: */
529: #define PetscStackCall(name,routine) PetscStackPush(name);routine;PetscStackPop;
539: #endif